stationery 0.7.0 → 0.8.0

data/lib/stationery/svg/style.rb

@@ -4,13 +4,17 @@ module Stationery
   module SVG
     # Presentation attributes an element inherits from its ancestors, and the
     # transform it draws with. An element's own values cascade: presentation
-    # attributes, then stylesheet rules, then its inline `style`.
+    # attributes, then stylesheet rules, then its inline `style`. `color` sets
+    # what `currentColor` means from the element down.
     class Style
-      INHERITED = %w[fill stroke stroke-width stroke-linecap stroke-linejoin fill-rule opacity fill-opacity
+      INHERITED = %w[fill stroke stroke-width stroke-linecap stroke-linejoin fill-rule clip-rule opacity fill-opacity
                      stroke-opacity font-family font-size font-weight font-style text-anchor visibility].freeze
+      # Properties of the element alone, not handed to its children.
+      LOCAL = %w[display clip-path overflow].freeze
       NAMED = { "black" => "#000000", "white" => "#FFFFFF", "red" => "#FF0000", "green" => "#008000",
                 "blue" => "#0000FF", "gray" => "#808080", "grey" => "#808080" }.freeze
       DEFAULTS = { "fill" => "black", "stroke" => "none", "stroke-width" => "1" }.freeze
+      IDENTITY = [1, 0, 0, 1, 0, 0].freeze
       URL = /\Aurl\(\s*['"]?#([^'")\s]+)['"]?\s*\)\s*(.*)\z/
 
       # A paint server reference, `url(#id)`, with its fallback colour (or nil).
@@ -32,34 +36,41 @@ module Stationery
 
       attr_reader :values, :matrix, :color
 
-      def initialize(values = DEFAULTS, matrix = [1, 0, 0, 1, 0, 0], color: "#000000", sheet: Stylesheet::EMPTY,
-                     display: nil)
+      def initialize(values = DEFAULTS, matrix = IDENTITY, color: "#000000", sheet: Stylesheet::EMPTY, local: {})
         @values = values
         @matrix = matrix
         @color = color
         @sheet = sheet
-        @display = display
+        @local = local
       end
 
       def child(element)
         attributes = element.attributes
         own = attributes.merge(@sheet.declarations(element), Style.declarations(attributes["style"]))
-        values = @values.merge(own.slice(*INHERITED))
-        matrix = if attributes["transform"]
-                   Transform.multiply(@matrix,
-                                      Transform.parse(attributes["transform"]))
-                 else
-                   @matrix
-                 end
-        Style.new(values, matrix, color: @color, sheet: @sheet, display: own["display"])
+        transform = attributes["transform"]
+        matrix = transform ? Transform.multiply(@matrix, Transform.parse(transform)) : @matrix
+        color = own["color"] ? Style.color(own["color"], @color) : @color
+        Style.new(@values.merge(own.slice(*INHERITED)), matrix, color:, sheet: @sheet, local: own.slice(*LOCAL))
       end
 
-      def displayed? = @display != "none"
+      # This style with `matrix` applied inside its transform: what a `use`
+      # does with its x and y, a viewport with its viewBox.
+      def transformed(matrix) = at(Transform.multiply(@matrix, matrix))
+
+      # This style drawing under another transform altogether.
+      def at(matrix, values = @values) = Style.new(values, matrix, color: @color, sheet: @sheet, local: @local)
+
+      def displayed? = @local["display"] != "none"
       def visible? = !%w[hidden collapse].include?(@values["visibility"])
+      # Whether a viewport clips what it draws: all but `visible` and `auto` do.
+      def clips? = !%w[visible auto].include?(@local["overflow"])
+      # The id of the element's `clip-path: url(#id)`, or nil.
+      def clip_path = @local["clip-path"].to_s.strip[URL, 1]
 
       def fill = paint("fill")
       def stroke = paint("stroke")
       def even_odd? = @values["fill-rule"] == "evenodd"
+      def clip_even_odd? = @values["clip-rule"] == "evenodd"
       def cap = @values["stroke-linecap"]&.to_sym
       def join = @values["stroke-linejoin"]&.to_sym
 

data/lib/stationery/svg/viewport.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Stationery
+  module SVG
+    # The rectangle a symbol or a nested svg draws into, and how its viewBox
+    # is fitted there by `preserveAspectRatio`. Lengths may be percentages of
+    # the viewport around it (`parent`, [width, height]); without a size it
+    # fills that viewport. A symbol sits at the origin of its `use`
+    # (`origin: false`), a nested svg at its own x and y.
+    class Viewport
+      ALIGNMENT = /\Ax(Min|Mid|Max)Y(Min|Mid|Max)(?:\s+(meet|slice))?\z/
+      FRACTIONS = { "Min" => 0.0, "Mid" => 0.5, "Max" => 1.0 }.freeze
+
+      attr_reader :x, :y, :width, :height
+
+      def initialize(attributes, parent, origin: true)
+        @x = origin ? length(attributes["x"], parent[0], 0) : 0
+        @y = origin ? length(attributes["y"], parent[1], 0) : 0
+        @width = length(attributes["width"], parent[0], parent[0])
+        @height = length(attributes["height"], parent[1], parent[1])
+        @view_box = read_view_box(attributes["viewBox"])
+        @aspect = attributes["preserveAspectRatio"].to_s.strip
+      end
+
+      def drawable?
+        @width.positive? && @height.positive? && (@view_box.nil? || @view_box.last(2).all?(&:positive?))
+      end
+
+      # The size percentages inside resolve against.
+      def size = @view_box ? @view_box.last(2) : [@width, @height]
+
+      # Content space to the user space the viewport sits in.
+      def matrix
+        return [1, 0, 0, 1, @x, @y] unless @view_box
+
+        vx, vy, vw, vh = @view_box
+        sx, sy = scales(@width.fdiv(vw), @height.fdiv(vh))
+        align_x, align_y = alignment
+        [sx, 0, 0, sy, @x + (align_x * (@width - (vw * sx))) - (vx * sx),
+         @y + (align_y * (@height - (vh * sy))) - (vy * sy)].map { |value| tidy(value) }
+      end
+
+      # Traces the viewport's rectangle, for clipping what overflows it.
+      def trace(path) = path.rounded_rect(@x, @y, @width, @height, 0)
+
+      private
+
+      def scales(horizontal, vertical)
+        return [horizontal, vertical] if @aspect == "none"
+
+        scale = slice? ? [horizontal, vertical].max : [horizontal, vertical].min
+        [scale, scale]
+      end
+
+      def slice? = @aspect.match(ALIGNMENT)&.[](3) == "slice"
+
+      # The share of the spare room put before the content on each axis.
+      def alignment
+        match = @aspect.match(ALIGNMENT)
+        match ? [FRACTIONS.fetch(match[1]), FRACTIONS.fetch(match[2])] : [0.5, 0.5]
+      end
+
+      def read_view_box(source)
+        values = source.to_s.split(/[\s,]+/).reject(&:empty?).map { |value| tidy(value.to_f) }
+        values if values.size == 4
+      end
+
+      def length(value, reference, default)
+        value = value.to_s.strip
+        return default if value.empty?
+
+        tidy(value.end_with?("%") ? value.to_f * reference / 100 : value.to_f)
+      end
+
+      def tidy(value) = value == value.round ? value.round : value
+    end
+  end
+end

data/lib/stationery/svg/walker.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module Stationery
+  module SVG
+    # Walks a document in paint order and yields every drawn shape and text
+    # with its resolved style. A `use` draws what it refers to at its x and
+    # y, a symbol (through `use` only) and a nested svg draw into their
+    # viewport, and what has a `clip-path` or overflows a viewport is walked
+    # inside `clipper`: a callable given the Region and a block, left out
+    # when the document is only read. What cannot be followed is in `issues`.
+    class Walker
+      RENDERED = (Shapes::NAMES + %w[text g use svg]).freeze
+      VIEWPORTS = %w[symbol svg].freeze
+
+      attr_reader :issues
+
+      # `ids` are the document's elements by id, `viewport` the [width,
+      # height] percentages resolve against at the root.
+      def initialize(ids, viewport, clipper: nil)
+        @ids = ids
+        @viewports = [viewport]
+        @clipper = clipper
+        @clip_paths = ClipPath.new(ids, self)
+        @issues = []
+        @measuring = false
+      end
+
+      # Yields what the children of `parent` draw; `style` is the parent's.
+      # `chain` holds the ids of the `use` targets being drawn.
+      def children(parent, style, chain = [], &)
+        parent.children.grep(Parser::Element).each { |element| node(element, style.child(element), chain, &) }
+      end
+
+      # The box of what `element` draws, in its own user space, clipping
+      # and text aside: [x, y, width, height], or nil when it has no area.
+      def box(element, style)
+        bounds = Bounds.new
+        measuring do
+          node(element, style.at(Style::IDENTITY), []) do |shape, own|
+            corners(shape, own.matrix).each { |x, y| bounds.line_to(x, y) } unless shape.name == "text"
+          end
+        end
+        bounds.box
+      end
+
+      def issue(message)
+        @issues << message unless @measuring
+        nil
+      end
+
+      private
+
+      # Anything else (defs, symbol, clipPath, a gradient, …) draws nothing
+      # where it stands.
+      def node(element, style, chain, &)
+        return unless RENDERED.include?(element.name) && style.displayed?
+
+        clipped(element, style) do
+          case element.name
+          when "g" then children(element, style, chain, &)
+          when "use" then use(element, style, chain, &)
+          when "svg" then viewport(element, element.attributes, style, chain, &)
+          else yield element, style if style.visible?
+          end
+        end
+      end
+
+      def use(element, style, chain, &)
+        target, id = target_of(element)
+        return unless target
+        return issue("use: circular reference ##{id}") if chain.include?(id)
+
+        attributes = element.attributes
+        placed = style.transformed([1, 0, 0, 1, Shapes.f(attributes, "x"), Shapes.f(attributes, "y")])
+        instance(target, placed.child(target), attributes.slice("width", "height"), chain + [id], &)
+      end
+
+      # A symbol or an svg drawn by a use takes the use's width and height.
+      def instance(target, style, size, chain, &)
+        return node(target, style, chain, &) unless VIEWPORTS.include?(target.name)
+        return unless style.displayed?
+
+        clipped(target, style) { viewport(target, target.attributes.merge(size), style, chain, &) }
+      end
+
+      def target_of(element)
+        href = (element.attributes["href"] || element.attributes["xlink:href"]).to_s.strip
+        return issue("use: no href") if href.empty?
+
+        id = href[/\A#(.+)/, 1]
+        target = @ids[id]
+        target ? [target, id] : issue("use: #{href} not found")
+      end
+
+      def viewport(element, attributes, style, chain, &)
+        port = Viewport.new(attributes, @viewports.last, origin: element.name == "svg")
+        return unless port.drawable?
+
+        region = Region.new([Region::Part.new(style.matrix, port)], false, nil) if style.clips?
+        clip(region) { within(port) { children(element, style.transformed(port.matrix), chain, &) } }
+      end
+
+      def within(port)
+        @viewports.push(port.size)
+        yield
+      ensure
+        @viewports.pop
+      end
+
+      def clipped(element, style, &)
+        id = style.clip_path
+        return yield if id.nil? || @measuring
+
+        region = @clip_paths.region(id, element, style)
+        region ? clip(region, &) : yield
+      end
+
+      def clip(region, &)
+        return yield if region.nil? || @measuring
+        return if region.empty?
+
+        @clipper ? @clipper.call(region, &) : yield
+      end
+
+      def measuring
+        previous = @measuring
+        @measuring = true
+        yield
+      ensure
+        @measuring = previous
+      end
+
+      def corners(shape, matrix)
+        x, y, width, height = Bounds.new.tap { |bounds| Shapes.trace(bounds, shape) }.box
+        return [] unless x
+
+        [[x, y], [x + width, y], [x, y + height], [x + width, y + height]]
+          .map { |corner_x, corner_y| Transform.apply(matrix, corner_x, corner_y) }
+      end
+    end
+  end
+end

data/lib/stationery/testing/inspector.rb

@@ -12,6 +12,9 @@ module Stationery
     # Needs the pdf-reader gem, loaded on first use.
     class Inspector
       UTF16_BOM = "\xFE\xFF".b
+      XMP_PROPERTY = %r{^\s*<((?!rdf:)[\w.-]+:[\w.-]+)>(.*?)</\1>$}
+      XMP_ITEM = %r{<rdf:li[^>]*>(.*?)</rdf:li>}
+      XMP_ENTITIES = { "&amp;" => "&", "&lt;" => "<", "&gt;" => ">", "&quot;" => '"' }.freeze
 
       def initialize(subject)
         @subject = subject
@@ -39,6 +42,45 @@ module Stationery
       def page_texts = @page_texts ||= reader.pages.map { |page| page.text.squeeze(" ").strip }
       def text = page_texts.join("\n")
       def metadata = reader.info
+
+      # The XMP packet (the catalog's /Metadata stream) as a String, or nil.
+      def xmp
+        return unless catalog[:Metadata]
+
+        objects.deref!(catalog[:Metadata]).unfiltered_data.dup.force_encoding(Encoding::UTF_8)
+      end
+
+      # The packet's properties by prefixed name (`"dc:title"`): a plain value
+      # as a String, an rdf:Alt as its default String, an rdf:Seq or rdf:Bag as
+      # an Array. Reads the packets Stationery writes (one property per line).
+      def xmp_values
+        packet = xmp
+        return {} unless packet
+
+        packet.scan(XMP_PROPERTY).to_h { |name, body| [name, xmp_value(body)] }
+      end
+
+      # The conformance levels the XMP packet claims, as PDF::Conformance
+      # names them: `[:pdf_a3b, :pdf_ua1]`, or [] without a claim.
+      def conformance
+        values = xmp_values
+        part, level, accessible = values.values_at("pdfaid:part", "pdfaid:conformance", "pdfuaid:part")
+        [part && :"pdf_a#{part}#{level.to_s.downcase}", accessible && :"pdf_ua#{accessible}"].compact
+      end
+
+      # The Factur-X / ZUGFeRD invoice the XMP packet names: `{ profile:
+      # :en16931, filename:, version:, xml: }` (xml nil when the file it
+      # names is not embedded), or nil for any other PDF.
+      def factur_x
+        values = xmp_values
+        filename = values["fx:DocumentFileName"]
+        return unless filename
+
+        file = attachments.find { |attachment| attachment[:name] == filename }
+        { profile: PDF::FacturX::PROFILES.key(values["fx:ConformanceLevel"]), filename:,
+          version: values["fx:Version"], xml: file && file[:bytes].dup.force_encoding(Encoding::UTF_8) }
+      end
+
       def image_count = pdf.scan(%r{/Subtype\s*/Image\b}).size
 
       def warnings
@@ -81,6 +123,16 @@ module Stationery
         PDF::PageLabels.labels(nums, page_count)
       end
 
+      # Every embedded file from the catalog's /EmbeddedFiles name tree:
+      # `{ name:, mime:, bytes:, description:, relationship: }` (bytes inflated).
+      def attachments
+        names = catalog.dig(:Names, :EmbeddedFiles)
+        return [] unless names
+
+        entries = objects.deref_array(objects.deref_hash(names)[:Names])
+        entries.each_slice(2).map { |_name, ref| attachment(objects.deref_hash(ref)) }
+      end
+
       # The structure tree of a tagged PDF as nested arrays; see StructureReader.
       def structure = @structure ||= StructureReader.new(reader).tree
 
@@ -108,6 +160,22 @@ module Stationery
         end
       end
 
+      def attachment(spec)
+        stream = objects.deref(objects.deref_hash(spec[:EF])[:F])
+        relationship = PDF::Attachments::RELATIONSHIPS.key(spec[:AFRelationship]) || spec[:AFRelationship]
+        { name: decode(spec[:UF] || spec[:F]), mime: stream.hash[:Subtype].to_s, bytes: stream.unfiltered_data,
+          description: spec[:Desc] && decode(spec[:Desc]), relationship: }
+      end
+
+      def xmp_value(body)
+        items = body.scan(XMP_ITEM).flatten.map { |item| xmp_text(item) }
+        return xmp_text(body) if items.empty?
+
+        body.start_with?("<rdf:Alt>") ? items.first : items
+      end
+
+      def xmp_text(value) = value.gsub(/&(amp|lt|gt|quot);/, XMP_ENTITIES)
+
       def destination(dest)
         return dest.to_s unless dest.is_a?(Array)
 

data/lib/stationery/testing/matchers.rb

@@ -119,6 +119,70 @@ module Stationery
         def actual = @inspector.page_labels.empty? ? "got none" : "got #{@inspector.page_labels.inspect}"
       end
 
+      class HaveConformance < Base
+        def initialize(*levels) = super(levels.flatten.map(&:to_sym))
+
+        def description = "conform to #{labels(@expected)}"
+
+        private
+
+        def labels(levels) = levels.map { |level| PDF::Conformance.label(level) }.join(" and ")
+        def match?(pdf) = (@expected - pdf.conformance).empty?
+        def actual = @inspector.conformance.empty? ? "got no claim" : "got #{labels(@inspector.conformance)}"
+      end
+
+      class HaveFacturX < Base
+        def initialize(profile: nil) = super(profile&.to_sym)
+
+        def description
+          @expected ? "be a Factur-X invoice of profile #{@expected.inspect}" : "be a Factur-X invoice"
+        end
+
+        private
+
+        def match?(pdf)
+          invoice = pdf.factur_x
+          !invoice.nil? && !invoice[:xml].nil? && (@expected.nil? || invoice[:profile] == @expected)
+        end
+
+        def actual
+          invoice = @inspector.factur_x
+          return "got no invoice" unless invoice
+          return "got #{invoice[:filename]} named in XMP but not embedded" unless invoice[:xml]
+
+          "got profile #{invoice[:profile].inspect}"
+        end
+      end
+
+      class HaveAttachment < Base
+        def initialize(name, mime: nil, relationship: nil)
+          super(name)
+          @mime = mime
+          @relationship = relationship
+        end
+
+        def description
+          extra = { mime: @mime, relationship: @relationship }.compact.map { |k, v| " #{k} #{v.inspect}" }.join
+          "have an attachment #{show(@expected)}#{extra}"
+        end
+
+        private
+
+        def match?(pdf)
+          pdf.attachments.any? do |file|
+            file[:name] == @expected && (@mime.nil? || file[:mime] == @mime) &&
+              (@relationship.nil? || file[:relationship] == @relationship)
+          end
+        end
+
+        def actual
+          files = @inspector.attachments
+          return "got none" if files.empty?
+
+          "got #{files.map { |file| "#{file[:name]} (#{file[:mime]}, #{file[:relationship]})" }.inspect}"
+        end
+      end
+
       class HaveNoWarnings < Base
         def description = "have no warnings"
 
@@ -160,6 +224,9 @@ module Stationery
       def have_bookmark(title) = HaveBookmark.new(title)
       def have_pdf_language(lang) = HaveLanguage.new(lang)
       def have_page_labels(labels) = HavePageLabels.new(labels)
+      def have_attachment(name, **) = HaveAttachment.new(name, **)
+      def have_conformance(*levels) = HaveConformance.new(*levels)
+      def have_factur_x(profile: nil) = HaveFacturX.new(profile:)
       def have_no_warnings = HaveNoWarnings.new
       def have_structure(expected) = HaveStructure.new(expected)
       def have_tagged_content = HaveTaggedContent.new

data/lib/stationery/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Stationery
-  VERSION = "0.7.0"
+  VERSION = "0.8.0"
 end

data/lib/stationery/warnings.rb

@@ -55,6 +55,10 @@ module Stationery
       def message = "tagged PDF has no language: set metadata lang:"
     end
 
+    ConformanceIssue = Data.define(:level, :subject) do
+      def message = "#{PDF::Conformance.label(level)}: #{subject} is not covered by the sRGB output intent"
+    end
+
     def initialize
       @items = []
       @glyphs = Hash.new(0)

data/lib/stationery.rb

@@ -62,6 +62,10 @@ require_relative "stationery/canvas/marking"
 require_relative "stationery/canvas"
 require_relative "stationery/pdf/outline_writer"
 require_relative "stationery/pdf/page_labels"
+require_relative "stationery/pdf/attachments"
+require_relative "stationery/pdf/xmp"
+require_relative "stationery/pdf/conformance"
+require_relative "stationery/pdf/factur_x"
 require_relative "stationery/forms/metrics"
 require_relative "stationery/forms/field"
 require_relative "stationery/forms/appearance"
@@ -108,6 +112,10 @@ require_relative "stationery/svg/gradient"
 require_relative "stationery/svg/shading"
 require_relative "stationery/svg/painter"
 require_relative "stationery/svg/text"
+require_relative "stationery/svg/viewport"
+require_relative "stationery/svg/region"
+require_relative "stationery/svg/clip_path"
+require_relative "stationery/svg/walker"
 require_relative "stationery/svg/document"
 require_relative "stationery/layout/svg"
 require_relative "stationery/layout/wrap"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: stationery
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -145,17 +145,23 @@ files:
 - lib/stationery/page.rb
 - lib/stationery/page_templates.rb
 - lib/stationery/pdf/assembler.rb
+- lib/stationery/pdf/attachments.rb
+- lib/stationery/pdf/conformance.rb
 - lib/stationery/pdf/encryption/aes.rb
 - lib/stationery/pdf/encryption/rc4.rb
 - lib/stationery/pdf/encryption/revision4.rb
 - lib/stationery/pdf/encryption/revision6.rb
 - lib/stationery/pdf/encryption/standard_security.rb
+- lib/stationery/pdf/factur_x.rb
+- lib/stationery/pdf/icc/LICENSE.md
+- lib/stationery/pdf/icc/sRGB2014.icc
 - lib/stationery/pdf/outline_writer.rb
 - lib/stationery/pdf/page_labels.rb
 - lib/stationery/pdf/serializer.rb
 - lib/stationery/pdf/stream.rb
 - lib/stationery/pdf/types.rb
 - lib/stationery/pdf/writer.rb
+- lib/stationery/pdf/xmp.rb
 - lib/stationery/preview.rb
 - lib/stationery/rails.rb
 - lib/stationery/rails/previews_controller.rb
@@ -171,11 +177,13 @@ files:
 - lib/stationery/structure.rb
 - lib/stationery/svg/arc.rb
 - lib/stationery/svg/bounds.rb
+- lib/stationery/svg/clip_path.rb
 - lib/stationery/svg/document.rb
 - lib/stationery/svg/gradient.rb
 - lib/stationery/svg/painter.rb
 - lib/stationery/svg/parser.rb
 - lib/stationery/svg/path_data.rb
+- lib/stationery/svg/region.rb
 - lib/stationery/svg/selector.rb
 - lib/stationery/svg/shading.rb
 - lib/stationery/svg/shapes.rb
@@ -183,6 +191,8 @@ files:
 - lib/stationery/svg/stylesheet.rb
 - lib/stationery/svg/text.rb
 - lib/stationery/svg/transform.rb
+- lib/stationery/svg/viewport.rb
+- lib/stationery/svg/walker.rb
 - lib/stationery/tagging/element.rb
 - lib/stationery/tagging/tree.rb
 - lib/stationery/tagging/writer.rb