idml 0.3.1 → 0.4.1

data/lib/idml/elements/table_cell.rb

@@ -3,13 +3,21 @@
 module Idml
   module Elements
     # `<TableCell>` — a single cell within a table row. Carries the
-    # cell's content type and dimensions.
+    # cell's content type, dimensions, and any inline text content
+    # (`<CharacterStyleRange>` children that carry the cell's text).
+    #
+    # IDML's actual schema (`Cell_Object` in
+    # `reference-docs/schemas/package/Stories/Story.rnc`) names this
+    # element `Cell` and includes many more attributes; this model
+    # captures the subset the renderer needs today.
     class TableCell < Lutaml::Model::Serializable
       attribute :self_attr, :string
       attribute :name, :string
       attribute :column, :integer
       attribute :row, :integer
       attribute :key_value, :string
+      attribute :character_style_range, Idml::Elements::CharacterStyleRange,
+                collection: true
 
       xml do
         root "TableCell"
@@ -18,6 +26,11 @@ module Idml
         map_attribute "Column", to: :column
         map_attribute "Row", to: :row
         map_attribute "KeyValue", to: :key_value
+        map_element "CharacterStyleRange", to: :character_style_range
+      end
+
+      def text_content
+        character_style_range.filter_map(&:text_content).join
       end
     end
   end

data/lib/idml/elements.rb

@@ -15,6 +15,7 @@ module Idml
     autoload :BevelAndEmbossSetting, "idml/elements/bevel_and_emboss_setting"
     autoload :BlendingSetting, "idml/elements/blending_setting"
     autoload :ButtonPreference, "idml/elements/pref_button_preference"
+    autoload :Bookmark, "idml/elements/bookmark"
     autoload :CellStyle, "idml/elements/cell_style"
     autoload :CellStyleGroup, "idml/elements/cell_style_group"
     autoload :ChapterNumberPreference,
@@ -60,6 +61,13 @@ module Idml
     autoload :Group, "idml/elements/group"
     autoload :GuidePreference, "idml/elements/pref_guide_preference"
     autoload :HTMLExportPreference, "idml/elements/pref_html_export_preference"
+    autoload :Hyperlink, "idml/elements/hyperlink"
+    autoload :HyperlinkPageDestination,
+             "idml/elements/hyperlink_page_destination"
+    autoload :HyperlinkTextSource,
+             "idml/elements/hyperlink_text_source"
+    autoload :HyperlinkURLDestination,
+             "idml/elements/hyperlink_url_destination"
     autoload :Image, "idml/elements/image"
     autoload :IndexHeaderSetting, "idml/elements/pref_index_header_setting"
     autoload :IndexOptions, "idml/elements/pref_index_options"

data/lib/idml/parts/designmap.rb

@@ -47,6 +47,12 @@ module Idml
       attribute :active_process, :string
 
       attribute :layer, Idml::Elements::Layer, collection: true
+      attribute :bookmark, Idml::Elements::Bookmark, collection: true
+      attribute :hyperlink, Idml::Elements::Hyperlink, collection: true
+      attribute :hyperlink_page_destination,
+                Idml::Elements::HyperlinkPageDestination, collection: true
+      attribute :hyperlink_url_destination,
+                Idml::Elements::HyperlinkURLDestination, collection: true
 
       xml do
         root "Document"
@@ -85,6 +91,12 @@ module Idml
         map_attribute "PreferMathMLInEpubExport", to: :prefer_math_ml_in_epub_export
         map_attribute "ActiveProcess", to: :active_process
         map_element "Layer", to: :layer
+        map_element "Bookmark", to: :bookmark
+        map_element "Hyperlink", to: :hyperlink
+        map_element "HyperlinkPageDestination",
+                    to: :hyperlink_page_destination
+        map_element "HyperlinkURLDestination",
+                    to: :hyperlink_url_destination
       end
     end
   end

data/lib/idml/render/bookmark_resolver.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Idml
+  module Render
+    # Resolves IDML bookmarks to (title, page_index) pairs ready for
+    # `PdfrbWriter#add_bookmark`. Uses the document's designmap to
+    # look up:
+    #
+    #   Bookmark#destination (Self) →
+    #     HyperlinkPageDestination#destination_page (Page Self) →
+    #       PDF page index (via spread iteration)
+    #
+    # Bookmarks whose destination chain cannot be resolved are
+    # skipped silently.
+    class BookmarkResolver
+      def initialize(package)
+        @package = package
+      end
+
+      # Yields [title, page_index] pairs for each resolvable bookmark.
+      def each
+        return enum_for(:each) unless block_given?
+
+        bookmarks.each do |bookmark|
+          entry = resolve(bookmark)
+          yield entry if entry
+        end
+      end
+
+      private
+
+      def bookmarks
+        designmap&.bookmark || []
+      end
+
+      def designmap
+        @package&.designmap
+      end
+
+      def resolve(bookmark)
+        destination = destination_by_self(bookmark.destination)
+        return nil unless destination&.destination_page
+
+        page_index = page_index_by_self(destination.destination_page)
+        return nil unless page_index
+
+        title = bookmark.name || destination.name || "Bookmark"
+        [title, page_index]
+      end
+
+      def destination_by_self(self_attr)
+        return nil unless self_attr
+
+        destinations.find { |d| d.self_attr == self_attr }
+      end
+
+      def destinations
+        designmap&.hyperlink_page_destination || []
+      end
+
+      def page_index_by_self(page_self)
+        page_self_table[page_self]
+      end
+
+      def page_self_table
+        @page_self_table ||= begin
+          table = {}
+          @package.spreads.each_with_index do |spread, spread_idx|
+            spread_pages = spread.spread.flat_map(&:page)
+            spread_pages.each_with_index do |page, page_idx|
+              table[page.self_attr] = cumulative_page_index(spread_idx, page_idx)
+            end
+          end
+          table
+        end
+      end
+
+      def cumulative_page_index(spread_idx, page_idx)
+        prior_pages = 0
+        @package.spreads.first(spread_idx).each do |spread|
+          prior_pages += spread.spread.flat_map(&:page).length
+        end
+        prior_pages + page_idx
+      end
+    end
+  end
+end

data/lib/idml/render/hyperlink_emitter.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Idml
+  module Render
+    # Emits PDF Link annotations for IDML hyperlinks. After a spread
+    # renders, walk each visible text frame, look up its story's
+    # hyperlink sources, resolve each to a URL via HyperlinkResolver,
+    # and emit a `/Subtype /Link` annotation over the frame's box.
+    #
+    # Limitation: this implementation is frame-level, not text-range
+    # level. The link covers the entire text frame rather than just
+    # the source's TextRange. Precise per-range rects require deeper
+    # integration with the text engine — see TODO 78.
+    class HyperlinkEmitter
+      def initialize(writer:, package:, page_height:, layer_filter: nil)
+        @writer = writer
+        @package = package
+        @resolver = HyperlinkResolver.new(package)
+        @page_height = page_height
+        @layer_filter = layer_filter
+      end
+
+      def emit_for(spread, page_index)
+        each_text_frame_on(spread) do |frame|
+          emit_for_frame(frame, page_index)
+        end
+      end
+
+      private
+
+      def each_text_frame_on(spread)
+        spread.each_page_item do |item|
+          next unless item.is_a?(Idml::Elements::TextFrame)
+          next if @layer_filter && !@layer_filter.visible?(item)
+
+          yield item
+        end
+      end
+
+      def emit_for_frame(frame, page_index)
+        urls = urls_for_frame(frame)
+        return if urls.empty?
+
+        box = Placement.box(frame, @page_height)
+        return unless box
+
+        urls.each do |url|
+          @writer.add_uri_link_annotation(
+            page_index: page_index,
+            rect: rect_for(box),
+            url: url,
+          )
+        end
+      end
+
+      def urls_for_frame(frame)
+        story = frame.parent_story ? @package.story_by_id(frame.parent_story) : nil
+        return [] unless story
+
+        sources = hyperlink_sources_in(story)
+        sources.filter_map { |source| @resolver.url_for_source(source.self_attr) }
+      end
+
+      def hyperlink_sources_in(story)
+        inner = story&.inner
+        return [] unless inner
+
+        inner.paragraph_style_range.flat_map do |psr|
+          psr.character_style_range.flat_map(&:hyperlink_text_source)
+        end.compact
+      end
+
+      def rect_for(box)
+        [box[:x], box[:y], box[:x] + box[:width], box[:y] + box[:height]]
+      end
+    end
+  end
+end

data/lib/idml/render/hyperlink_resolver.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Idml
+  module Render
+    # Resolves IDML hyperlink definitions to URL destinations. Looks
+    # up `Hyperlink#source` → `Hyperlink#destination` →
+    # `HyperlinkURLDestination#destination_url` from the designmap.
+    #
+    # The renderer is responsible for mapping source Self IDs to
+    # page-item rectangles; this resolver only handles the
+    # destination lookup.
+    class HyperlinkResolver
+      def initialize(package)
+        @package = package
+      end
+
+      # Returns the URL for the given hyperlink-source Self, or nil.
+      def url_for_source(source_self)
+        return nil unless source_self
+
+        hyperlink = hyperlink_by_source(source_self)
+        return nil unless hyperlink
+
+        url_destination_by_self(hyperlink.destination)&.destination_url
+      end
+
+      # Yields [source_self, url] for every visible hyperlink whose
+      # destination chain resolves to a URL.
+      def each_visible
+        return enum_for(:each_visible) unless block_given?
+
+        hyperlinks.each do |hyperlink|
+          entry = visible_entry(hyperlink)
+          yield(*entry) if entry
+        end
+      end
+
+      private
+
+      def visible_entry(hyperlink)
+        return nil if hyperlink.visible == false || hyperlink.hidden == true
+
+        url = url_destination_by_self(hyperlink.destination)&.destination_url
+        return nil unless url
+
+        [hyperlink.source, url]
+      end
+
+      def hyperlinks
+        @package&.designmap&.hyperlink || []
+      end
+
+      def hyperlink_by_source(source_self)
+        hyperlinks.find { |h| h.source == source_self }
+      end
+
+      def url_destination_by_self(self_attr)
+        return nil unless self_attr
+
+        url_destinations.find { |d| d.self_attr == self_attr }
+      end
+
+      def url_destinations
+        @package&.designmap&.hyperlink_url_destination || []
+      end
+    end
+  end
+end

data/lib/idml/render/icc_profile.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Idml
+  module Render
+    # Locates an sRGB ICC profile for PDF/A output intent embedding.
+    # The idml gem does not bundle a binary ICC asset; instead, this
+    # helper probes a small set of well-known locations in priority
+    # order and returns the first match as raw bytes.
+    #
+    # Priority:
+    #   1. `ENV["IDML_SRGB_ICC"]` — explicit user override.
+    #   2. `data/idml/srgb.icc` inside the gem tree (user-vendored).
+    #   3. macOS system profile at
+    #      `/System/Library/ColorSync/Profiles/sRGB Profile.icc`.
+    #
+    # Returns `nil` when no profile is available — callers (Pipeline)
+    # should skip ICC embedding in that case rather than raising.
+    module IccProfile
+      GEM_DATA_PATH = File.expand_path("../../../data/idml/srgb.icc", __dir__)
+      MACOS_SYSTEM_PATH = "/System/Library/ColorSync/Profiles/sRGB Profile.icc"
+
+      def self.srgb_bytes
+        candidate_paths.each do |path|
+          bytes = read_if_present(path)
+          return bytes if bytes
+        end
+        nil
+      end
+
+      def self.candidate_paths
+        [
+          ENV.fetch("IDML_SRGB_ICC", nil),
+          GEM_DATA_PATH,
+          MACOS_SYSTEM_PATH,
+        ].compact
+      end
+      private_class_method :candidate_paths
+
+      def self.read_if_present(path)
+        return nil unless path && !path.empty?
+        return nil unless File.exist?(path)
+
+        File.binread(path)
+      rescue StandardError
+        nil
+      end
+      private_class_method :read_if_present
+    end
+  end
+end

data/lib/idml/render/metadata_builder.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Idml
+  module Render
+    # Builds the PDF Info-dict metadata hash by merging XMP-extracted
+    # values from `META-INF/metadata.xml` over sensible defaults.
+    # Extracted from `Pipeline` for SRP — Pipeline orchestrates
+    # rendering, this module owns metadata assembly.
+    class MetadataBuilder
+      XMP_PATH = "META-INF/metadata.xml"
+
+      def initialize(package)
+        @package = package
+      end
+
+      # Returns a hash with Producer/CreationDate defaults, overridden
+      # by any XMP-supplied fields (Title, Author, Subject, Keywords,
+      # Creator, CreationDate, ModDate). XMP dates are converted from
+      # ISO 8601 to PDF `D:YYYYMMDDHHmmss` format.
+      def build
+        defaults.merge(xmp_fields) { |_key, default, xmp| xmp || default }
+      end
+
+      private
+
+      def defaults
+        {
+          Producer: "idml gem v#{Idml::VERSION}",
+          CreationDate: pdf_date(Time.now.utc),
+        }
+      end
+
+      def xmp_fields
+        return {} unless xmp_packet
+
+        {
+          Title: xmp_packet.title,
+          Author: xmp_packet.author,
+          Subject: xmp_packet.description,
+          Keywords: xmp_packet.keywords,
+          Creator: xmp_packet.creator_tool,
+          CreationDate: pdf_date_string(xmp_packet.create_date),
+          ModDate: pdf_date_string(xmp_packet.modify_date),
+        }.compact
+      end
+
+      def xmp_packet
+        return nil unless @package.has_part?(XMP_PATH)
+
+        @xmp_packet ||= begin
+          xml = @package.read_part(XMP_PATH)
+          Parts::XmpMeta.from_xml(xml).rdf
+        rescue StandardError
+          nil
+        end
+      end
+
+      def pdf_date_string(iso8601)
+        return nil unless iso8601
+
+        pdf_date(Time.iso8601(iso8601))
+      rescue ArgumentError
+        nil
+      end
+
+      def pdf_date(time)
+        time.strftime("D:%Y%m%d%H%M%S+00'00'")
+      end
+    end
+  end
+end

data/lib/idml/render/pdfrb_writer.rb

@@ -83,6 +83,16 @@ module Idml
                                               page: page, mcid: mcid)
       end
 
+      def add_uri_link_annotation(page_index:, rect:, url:)
+        page = @document.pages[page_index]
+        action = @document.add({ S: :URI, URI: url },
+                               type: Pdfrb::Model::Cos::Dictionary)
+        action_ref = Pdfrb::Model::Reference.new(action.oid, action.gen)
+        annot = @document.annotations.add(page, subtype: :Link, rect: rect)
+        annot.value[:A] = action_ref
+        annot
+      end
+
       def build_structure
         @document.structure.build!
       end

data/lib/idml/render/pipeline.rb

@@ -21,10 +21,13 @@ module Idml
 
       def call
         writer = PdfrbWriter.new
-        metadata = combined_metadata
+        metadata = MetadataBuilder.new(@package).build
         writer.set_info(metadata)
         writer.enable_tagged if @tagged
-        PdfaPacket.attach(writer.document, metadata) if pdfa_requested?
+        if pdfa_requested?
+          PdfaPacket.attach(writer.document, metadata)
+          embed_pdfa_output_intent(writer)
+        end
         structure = StructureTracker.new(enabled: @tagged)
         layer_filter = LayerFilter.from_designmap(@package.designmap)
         font_ref_resolver = FontReferenceResolver.build(@package)
@@ -42,6 +45,7 @@ module Idml
 
         structure.flush(writer)
         writer.build_structure if @tagged
+        emit_bookmarks(writer)
         writer.subset_fonts! if @subset_fonts
         writer.write(@output_path)
         @output_path
@@ -49,6 +53,26 @@ module Idml
 
       private
 
+      def embed_pdfa_output_intent(writer)
+        bytes = IccProfile.srgb_bytes
+        return unless bytes
+
+        writer.document.output_intents.embed_icc(
+          bytes,
+          identifier: "sRGB",
+          condition: "sRGB IEC61966-2.1",
+          subtype: :GTS_PDFA1,
+        )
+      rescue StandardError
+        nil
+      end
+
+      def emit_bookmarks(writer)
+        BookmarkResolver.new(@package).each do |title, page_index|
+          writer.add_bookmark(title, page_index)
+        end
+      end
+
       def pdfa_requested?
         @compliance&.to_s&.start_with?("pdfa")
       end
@@ -71,10 +95,20 @@ module Idml
                                           page_height: dims[:height],
                                           image_refs: image_refs,
                                           page_index: current)
+          emit_hyperlinks(writer, spread, current, layer_filter)
         end
         current
       end
 
+      def emit_hyperlinks(writer, spread, page_index, layer_filter)
+        HyperlinkEmitter.new(writer: writer, package: @package,
+                             page_height: DEFAULT_HEIGHT,
+                             layer_filter: layer_filter)
+          .emit_for(spread, page_index)
+      rescue StandardError
+        nil
+      end
+
       def build_renderer(layer_filter, font_ref_resolver, font_resource,
                          font_metrics, structure:)
         SpreadRenderer.new(
@@ -135,60 +169,6 @@ module Idml
         end
         nil
       end
-
-      def combined_metadata
-        defaults = default_metadata
-        xmp_metadata.each do |key, value|
-          next if value.nil? || value.empty?
-
-          defaults[key] = value
-        end
-        defaults
-      end
-
-      def xmp_metadata
-        return {} unless @package.has_part?(XMP_PATH)
-
-        xml = @package.read_part(XMP_PATH)
-        meta = Parts::XmpMeta.from_xml(xml)
-        rdf = meta.rdf
-        return {} unless rdf
-
-        {
-          Title: rdf.title,
-          Author: rdf.author,
-          Subject: rdf.description,
-          Keywords: rdf.keywords,
-          Creator: rdf.creator_tool,
-          CreationDate: pdf_date_string(rdf.create_date),
-          ModDate: pdf_date_string(rdf.modify_date),
-        }
-      rescue StandardError
-        {}
-      end
-
-      def pdf_date_string(iso8601)
-        return nil unless iso8601
-
-        time = Time.iso8601(iso8601)
-        pdf_date(time)
-      rescue ArgumentError
-        nil
-      end
-
-      def default_metadata
-        {
-          Producer: "idml gem v#{Idml::VERSION}",
-          CreationDate: pdf_date(Time.now.utc),
-        }
-      end
-
-      def pdf_date(time)
-        time.strftime("D:%Y%m%d%H%M%S+00'00'")
-      end
-
-      XMP_PATH = "META-INF/metadata.xml"
-      private_constant :XMP_PATH
     end
   end
 end

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

@@ -3,7 +3,14 @@
 module Idml
   module Render
     module Renderers
+      # Renders an IDML Table. Draws the cell grid via rectangle ops,
+      # then renders inline `<CharacterStyleRange>` text in each cell
+      # via `canvas.text_rich`. Cells with no text render as empty
+      # rectangles.
       class TableRenderer
+        DEFAULT_SIZE = 10.0
+        INSET = 4.0
+
         def self.render(canvas, context)
           table = context.item
           return if table.visible == false
@@ -17,24 +24,41 @@ module Idml
 
           canvas.save_graphics_state do
             table.table_row.each_with_index do |row, row_index|
-              render_row(canvas, row, row_index, row_count, box, row_height)
+              render_row(canvas, row, row_index, row_count, box, row_height,
+                         context)
             end
           end
         end
 
-        def self.render_row(canvas, row, row_index, row_count, box, row_height)
+        def self.render_row(canvas, row, row_index, row_count, box, row_height,
+                            context)
           row_y = box[:y] + ((row_count - 1 - row_index) * row_height)
           cell_count = row.table_cell.length
           return unless cell_count.positive?
 
           cell_width = box[:width] / cell_count
-          row.table_cell.each_with_index do |_cell, cell_index|
+          row.table_cell.each_with_index do |cell, cell_index|
             cell_x = box[:x] + (cell_index * cell_width)
             canvas.rectangle(cell_x, row_y, cell_width, row_height)
             canvas.stroke
+            render_cell_text(canvas, cell, cell_x, row_y, row_height, context)
           end
         end
         private_class_method :render_row
+
+        def self.render_cell_text(canvas, cell, x, y, height, context)
+          text = cell.text_content
+          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
       end
     end
   end