idml 0.2.8 → 0.3.0

data/lib/idml/parts/xmp.rb

@@ -0,0 +1,305 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Idml
+  module Parts
+    # XMP (Extensible Metadata Platform) parser for IDML's
+    # `META-INF/metadata.xml`. The packet is RDF/XML with multiple
+    # namespaces (`dc:`, `xmp:`, `pdf:`, `xmpMM:`, etc.).
+    #
+    # Per Lutaml's namespace API, each namespaced element is a
+    # separate `Serializable` subclass that carries its own
+    # `namespace`. The parent `<rdf:Description>` composes the
+    # children via `map_element`, with the namespace binding handled
+    # on each child class.
+    module Xmp
+      class RdfNamespace < Lutaml::Xml::Namespace
+        uri "http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+        prefix_default "rdf"
+      end
+
+      class DcNamespace < Lutaml::Xml::Namespace
+        uri "http://purl.org/dc/elements/1.1/"
+        prefix_default "dc"
+      end
+
+      class XmpNamespace < Lutaml::Xml::Namespace
+        uri "http://ns.adobe.com/xap/1.0/"
+        prefix_default "xmp"
+      end
+
+      class XmetaNamespace < Lutaml::Xml::Namespace
+        uri "adobe:ns:meta/"
+        prefix_default "x"
+      end
+
+      # Single direct-value element. Subclasses set the element name
+      # and namespace.
+      class Leaf < Lutaml::Model::Serializable
+        attribute :value, :string
+      end
+
+      class Format < Leaf
+        xml do
+          root "format"
+          namespace DcNamespace
+          map_content to: :value
+        end
+      end
+
+      class CreatorTool < Leaf
+        xml do
+          root "CreatorTool"
+          namespace XmpNamespace
+          map_content to: :value
+        end
+      end
+
+      class CreateDate < Leaf
+        xml do
+          root "CreateDate"
+          namespace XmpNamespace
+          map_content to: :value
+        end
+      end
+
+      class ModifyDate < Leaf
+        xml do
+          root "ModifyDate"
+          namespace XmpNamespace
+          map_content to: :value
+        end
+      end
+
+      class MetadataDate < Leaf
+        xml do
+          root "MetadataDate"
+          namespace XmpNamespace
+          map_content to: :value
+        end
+      end
+
+      # rdf:li element inside rdf:Alt / rdf:Seq / rdf:Bag containers.
+      class ListItem < Lutaml::Model::Serializable
+        attribute :lang, :string
+        attribute :value, :string
+
+        xml do
+          root "li"
+          namespace RdfNamespace
+          map_attribute "lang", to: :lang
+          map_content to: :value
+        end
+      end
+
+      # rdf:Alt — alternative-language values. Used for dc:title and
+      # dc:description.
+      class Alt < Lutaml::Model::Serializable
+        attribute :items, ListItem, collection: true
+
+        xml do
+          root "Alt"
+          namespace RdfNamespace
+          map_element "li", to: :items
+        end
+
+        def default_value
+          x_default = items.find { |i| i.lang == "x-default" }
+          (x_default || items.first)&.value
+        end
+      end
+
+      # rdf:Seq — ordered sequence. Used for dc:creator.
+      class Seq < Lutaml::Model::Serializable
+        attribute :items, ListItem, collection: true
+
+        xml do
+          root "Seq"
+          namespace RdfNamespace
+          map_element "li", to: :items
+        end
+
+        def values
+          items.filter_map(&:value)
+        end
+      end
+
+      # rdf:Bag — unordered set. Used for dc:subject.
+      class Bag < Lutaml::Model::Serializable
+        attribute :items, ListItem, collection: true
+
+        xml do
+          root "Bag"
+          namespace RdfNamespace
+          map_element "li", to: :items
+        end
+
+        def values
+          items.filter_map(&:value)
+        end
+      end
+
+      # Container-wrapped dc elements.
+      class Title < Lutaml::Model::Serializable
+        attribute :alt, Alt
+
+        xml do
+          root "title"
+          namespace DcNamespace
+          map_element "Alt", to: :alt
+        end
+
+        def value
+          alt&.default_value
+        end
+      end
+
+      class DcDescription < Lutaml::Model::Serializable
+        attribute :alt, Alt
+
+        xml do
+          root "description"
+          namespace DcNamespace
+          map_element "Alt", to: :alt
+        end
+
+        def value
+          alt&.default_value
+        end
+      end
+
+      class Creator < Lutaml::Model::Serializable
+        attribute :seq, Seq
+
+        xml do
+          root "creator"
+          namespace DcNamespace
+          map_element "Seq", to: :seq
+        end
+
+        def values
+          seq&.values || []
+        end
+      end
+
+      class Subject < Lutaml::Model::Serializable
+        attribute :bag, Bag
+
+        xml do
+          root "subject"
+          namespace DcNamespace
+          map_element "Bag", to: :bag
+        end
+
+        def values
+          bag&.values || []
+        end
+      end
+    end
+
+    # Single `<rdf:Description>` element from an XMP packet. Combines
+    # children from multiple namespaces (`dc:`, `xmp:`) by composing
+    # nested `Serializable` models — each child carries its own
+    # `namespace` declaration per Lutaml's namespace API.
+    class XmpDescription < Lutaml::Model::Serializable
+      attribute :format, Xmp::Format
+      attribute :title, Xmp::Title
+      attribute :creator, Xmp::Creator
+      attribute :description, Xmp::DcDescription
+      attribute :subject, Xmp::Subject
+      attribute :creator_tool, Xmp::CreatorTool
+      attribute :create_date, Xmp::CreateDate
+      attribute :modify_date, Xmp::ModifyDate
+      attribute :metadata_date, Xmp::MetadataDate
+
+      xml do
+        root "Description"
+        namespace Xmp::RdfNamespace
+        map_element "format", to: :format
+        map_element "title", to: :title
+        map_element "creator", to: :creator
+        map_element "description", to: :description
+        map_element "subject", to: :subject
+        map_element "CreatorTool", to: :creator_tool
+        map_element "CreateDate", to: :create_date
+        map_element "ModifyDate", to: :modify_date
+        map_element "MetadataDate", to: :metadata_date
+      end
+
+      def author
+        creator&.values&.first
+      end
+
+      def keywords
+        subject&.values&.join(", ")
+      end
+    end
+
+    # `<rdf:RDF>` — collection of `<rdf:Description>` siblings inside
+    # an XMP packet. Per IDML's META-INF/metadata.xml, there is
+    # typically one Description per schema group.
+    class XmpRdf < Lutaml::Model::Serializable
+      attribute :descriptions, XmpDescription, collection: true
+
+      xml do
+        root "RDF"
+        namespace Xmp::RdfNamespace
+        map_element "Description", to: :descriptions
+      end
+
+      # Merged view across all Descriptions. Each attribute returns
+      # the first non-nil value across the descriptions.
+      def first_description
+        descriptions.first
+      end
+
+      def title
+        descriptions.map(&:title).find(&:itself)&.value
+      end
+
+      def author
+        descriptions.filter_map(&:author).first
+      end
+
+      def subject
+        descriptions.filter_map(&:subject).find(&:itself)&.values
+      end
+
+      def keywords
+        subject&.join(", ")
+      end
+
+      def description
+        descriptions.map(&:description).find(&:itself)&.value
+      end
+
+      def creator_tool
+        descriptions.filter_map(&:creator_tool).first&.value
+      end
+
+      def create_date
+        descriptions.filter_map(&:create_date).first&.value
+      end
+
+      def modify_date
+        descriptions.filter_map(&:modify_date).first&.value
+      end
+    end
+
+    # `<x:xmpmeta>` — outer wrapper of an XMP packet.
+    class XmpMeta < Lutaml::Model::Serializable
+      attribute :rdf, XmpRdf
+
+      xml do
+        root "xmpmeta"
+        namespace Xmp::XmetaNamespace
+        map_element "RDF", to: :rdf
+      end
+
+      def description
+        rdf&.first_description
+      end
+    end
+  end
+end

data/lib/idml/parts.rb

@@ -15,6 +15,10 @@ module Idml
     autoload :Preferences,  "idml/parts/preferences"
     autoload :Tags,         "idml/parts/tags"
     autoload :Mapping,      "idml/parts/mapping"
+    autoload :Xmp,            "idml/parts/xmp"
+    autoload :XmpDescription, "idml/parts/xmp"
+    autoload :XmpRdf,         "idml/parts/xmp"
+    autoload :XmpMeta,        "idml/parts/xmp"
 
     @registry = {}
 

data/lib/idml/render/image_collector.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Idml
+  module Render
+    # Walks a Spread's page items, resolves image URIs against the
+    # package's base directory, deduplicates by URI, and emits
+    # placement refs (`{ name:, placement:, clip_box: }`) ready for
+    # `SpreadRenderer#render_images`.
+    #
+    # Extracted from `Pipeline` so the pipeline stays a sequence of
+    # high-level steps and the image-loading details live behind one
+    # object. Owns: file I/O, format detection, deduplication,
+    # placement math. Does not own: rendering (SpreadRenderer draws),
+    # layer filtering (caller passes a visible-only iterable).
+    class ImageCollector
+      DEFAULT_PAGE_HEIGHT = 792
+
+      def initialize(writer:, base_dir:, page_height: DEFAULT_PAGE_HEIGHT)
+        @writer = writer
+        @base_dir = base_dir
+        @page_height = page_height
+      end
+
+      # Enumerate every page item in `spread`, register its image
+      # children with the writer, and return the list of placement
+      # refs. Items whose `image` collection is empty or whose URIs
+      # cannot be resolved are skipped silently.
+      def collect(spread)
+        refs = []
+        spread.each_page_item do |item|
+          images_for(item).each do |image|
+            ref = register(image, item)
+            refs << ref if ref
+          end
+        end
+        refs
+      end
+
+      private
+
+      def images_for(item)
+        case item
+        when Idml::Elements::Rectangle, Idml::Elements::Polygon
+          item.image || []
+        else
+          []
+        end
+      end
+
+      def register(image, parent)
+        uri = image.resource_uri
+        return nil unless uri
+
+        existing = @writer.image_name_for(uri)
+        return reuse(existing, image, parent) if existing
+
+        load_new(image, parent, uri)
+      end
+
+      def reuse(name, image, parent)
+        { name: name, placement: placement_for(image, parent),
+          clip_box: clip_box_for(parent) }
+      end
+
+      def load_new(image, parent, uri)
+        path = Image.resolve_path(uri, base_dir: @base_dir)
+        return nil unless File.exist?(path)
+
+        data = File.binread(path)
+        dims = dimensions_of(data)
+        return nil unless dims
+
+        name = @writer.add_image(data: data)
+        @writer.register_image_name(uri, name)
+        { name: name, placement: placement_for(image, parent, dims[1]),
+          clip_box: clip_box_for(parent) }
+      end
+
+      def clip_box_for(parent)
+        return nil unless parent.geometric_bounds
+
+        Geometry.placement_rect(parent.geometric_bounds,
+                                parent.item_transform, @page_height)
+      end
+
+      def dimensions_of(data)
+        format = Image.detect_format(data)
+        return nil unless format
+
+        format == :png ? Image.png_dimensions(data) : Image.jpeg_dimensions(data)
+      end
+
+      def placement_for(image, parent, pixel_height = 100)
+        Image.compute_placement(
+          image_transform: parse_transform(image.item_transform),
+          parent_transform: parse_transform(parent.item_transform),
+          pixel_height: pixel_height,
+          page_height: @page_height,
+        )
+      end
+
+      def parse_transform(raw)
+        Image.parse_transform(raw) || Image.identity
+      end
+    end
+  end
+end

data/lib/idml/render/page_item_renderer.rb

@@ -20,7 +20,11 @@ module Idml
         renderer = renderer_for(context.item)
         return nil unless renderer
 
-        renderer.render(canvas, context)
+        if context.structure&.enabled?
+          wrap_tagged(canvas, context) { renderer.render(canvas, context) }
+        else
+          renderer.render(canvas, context)
+        end
       end
 
       def self.renderer_for(item)
@@ -29,6 +33,19 @@ module Idml
 
         Render::Renderers.const_get(renderer_name)
       end
+
+      def self.wrap_tagged(canvas, context, &)
+        type = StructureMapper.type_for(context.item)
+        return yield unless type
+
+        tracker = context.structure
+        page_index = context.page_index || 0
+        mcid = tracker.next_mcid(page_index)
+        alt = StructureMapper.alt_for(context.item)
+        tracker.add(type, page_index: page_index, mcid: mcid, alt: alt)
+        canvas.tagged(type, mcid: mcid, &)
+      end
+      private_class_method :wrap_tagged
     end
   end
 end

data/lib/idml/render/pdfa_packet.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module Idml
+  module Render
+    # Builds the PDF/A-2a XMP packet and attaches it to the PDF
+    # Catalog as the `/Metadata` stream. PDF/A requires:
+    #
+    #   1. An XMP metadata stream on `/Catalog` (not just `/Info`).
+    #   2. The packet must declare `pdfaid:part` and `pdfaid:conformance`.
+    #   3. `dc:format` must be `application/pdf`.
+    #
+    # ICC profile (output intent) embedding is handled separately by
+    # `OutputIntents#embed_icc` — see TODO 77 for the deferred plan
+    # to bundle sRGB and register the intent.
+    #
+    # The packet is built from the same fields already threaded
+    # through `PdfrbWriter#set_info`, so PDF/A output reuses the
+    # XMP-extracted values from the IDML packet (TODO 75).
+    module PdfaPacket
+      PDF_A_PART = 2
+      PDF_A_CONFORMANCE = "A"
+
+      # Returns the XMP packet bytes suitable for a `/Metadata` stream.
+      # @param metadata [Hash{Symbol => String}] the Info-dict fields
+      #   already assembled by the pipeline.
+      def self.build(metadata)
+        body = rdf_description(metadata)
+        "#{XMP_BEGIN}#{body}#{XMP_END}"
+      end
+
+      # Attaches the built packet to the document's Catalog as the
+      # `/Metadata` stream and sets `/Lang`. Idempotent — replaces
+      # any existing `/Metadata`.
+      def self.attach(document, metadata)
+        xmp = build(metadata)
+        stream = document.add(
+          { Type: :Metadata, Subtype: :XML, Length: xmp.bytesize },
+          type: Pdfrb::Model::Cos::Stream,
+        )
+        stream.stream = xmp
+        document.catalog.value[:Metadata] =
+          Pdfrb::Model::Reference.new(stream.oid, stream.gen)
+        document.catalog.value[:Lang] ||= "en-US"
+      end
+
+      XMP_BEGIN = "<?xpacket begin=\"\" id=\"W5M0MpCehiHzreSzNTczkc9d\"?>\n"
+      XMP_END = "<?xpacket end=\"w\"?>\n"
+      private_constant :XMP_BEGIN, :XMP_END
+
+      def self.rdf_description(metadata)
+        lines = [
+          '<x:xmpmeta xmlns:x="adobe:ns:meta/">',
+          '<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">',
+          '<rdf:Description rdf:about=""',
+          '    xmlns:dc="http://purl.org/dc/elements/1.1/"',
+          '    xmlns:pdf="http://ns.adobe.com/pdf/1.3/"',
+          '    xmlns:xmp="http://ns.adobe.com/xap/1.0/"',
+          '    xmlns:pdfaid="http://www.aiim.org/pdfa/ns/id/">',
+        ]
+        lines += pdfaid_lines
+        lines += dc_lines(metadata)
+        lines += pdf_lines(metadata)
+        lines += xmp_lines(metadata)
+        lines << "</rdf:Description>"
+        lines << "</rdf:RDF>"
+        lines << "</x:xmpmeta>"
+        "#{lines.join("\n")}\n"
+      end
+      private_class_method :rdf_description
+
+      def self.pdfaid_lines
+        [
+          "  <pdfaid:part>#{PDF_A_PART}</pdfaid:part>",
+          "  <pdfaid:conformance>#{PDF_A_CONFORMANCE}</pdfaid:conformance>",
+        ]
+      end
+      private_class_method :pdfaid_lines
+
+      def self.dc_lines(metadata)
+        lines = []
+        if metadata[:Title]
+          lines << '  <dc:title><rdf:Alt><rdf:li xml:lang="x-default">' \
+                   "#{escape(metadata[:Title])}</rdf:li></rdf:Alt></dc:title>"
+        end
+        if metadata[:Author]
+          lines << "  <dc:creator><rdf:Seq>" \
+                   "<rdf:li>#{escape(metadata[:Author])}</rdf:li>" \
+                   "</rdf:Seq></dc:creator>"
+        end
+        if metadata[:Subject]
+          lines << '  <dc:description><rdf:Alt><rdf:li xml:lang="x-default">' \
+                   "#{escape(metadata[:Subject])}</rdf:li></rdf:Alt></dc:description>"
+        end
+        lines
+      end
+      private_class_method :dc_lines
+
+      def self.pdf_lines(metadata)
+        return [] unless metadata[:Keywords]
+
+        ["  <pdf:Keywords>#{escape(metadata[:Keywords])}</pdf:Keywords>"]
+      end
+      private_class_method :pdf_lines
+
+      def self.xmp_lines(metadata)
+        lines = []
+        lines << "  <dc:format>application/pdf</dc:format>"
+        if metadata[:Creator]
+          lines << "  <xmp:CreatorTool>#{escape(metadata[:Creator])}</xmp:CreatorTool>"
+        end
+        lines << xmp_date_line("CreateDate", metadata[:CreationDate])
+        lines << xmp_date_line("ModifyDate", metadata[:ModDate])
+        lines << xmp_date_line("MetadataDate", metadata[:CreationDate])
+        lines.compact
+      end
+      private_class_method :xmp_lines
+
+      def self.xmp_date_line(name, value)
+        return nil unless value
+
+        "  <xmp:#{name}>#{escape(value)}</xmp:#{name}>"
+      end
+      private_class_method :xmp_date_line
+
+      def self.escape(text)
+        text.to_s
+          .gsub("&", "&amp;")
+          .gsub("<", "&lt;")
+          .gsub(">", "&gt;")
+          .gsub('"', "&quot;")
+      end
+      private_class_method :escape
+    end
+  end
+end

data/lib/idml/render/pdfrb_writer.rb

@@ -78,8 +78,9 @@ module Idml
       end
 
       def add_structure_element(type, page_index:, mcid:, text: nil, alt: nil)
+        page = @document.pages[page_index]
         @document.structure.add_element(type, text: text, alt: alt,
-                                              page: page_index, mcid: mcid)
+                                              page: page, mcid: mcid)
       end
 
       def build_structure