stationery 0.6.0 → 0.8.0

data/lib/stationery/pdf/conformance.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module Stationery
+  module PDF
+    # The archival and accessibility standards a render claims, and what each
+    # asks of the file: PDF/A-2b and PDF/A-3b (ISO 19005-2/3, level B) and
+    # PDF/UA-1 (ISO 14289-1). Levels combine: `Conformance.new(:pdf_a3b, :pdf_ua1)`.
+    #
+    # A claim is only written when the document keeps it: what cannot be made
+    # conformant raises (ArgumentError for options that contradict the level,
+    # ConformanceError for content), so a file is never mislabelled.
+    class Conformance
+      LEVELS = {
+        pdf_a2b: { standard: :pdf_a, part: 2, conformance: "B", label: "PDF/A-2b" },
+        pdf_a3b: { standard: :pdf_a, part: 3, conformance: "B", label: "PDF/A-3b" },
+        pdf_ua1: { standard: :pdf_ua, part: 1, label: "PDF/UA-1" }
+      }.freeze
+      PDFA_ID = "http://www.aiim.org/pdfa/ns/id/"
+      PDFUA_ID = "http://www.aiim.org/pdfua/ns/id/"
+      # PDF/A knows its own schema; PDF/UA's has to be described to it.
+      PDFUA_SCHEMA = {
+        name: "PDF/UA identification schema", uri: PDFUA_ID, prefix: "pdfuaid",
+        properties: [{ name: "part", type: "Integer", category: "internal",
+                       description: "The part of ISO 14289 the document conforms to" }]
+      }.freeze
+      ICC_PROFILE = File.expand_path("icc/sRGB2014.icc", __dir__)
+      OUTPUT_CONDITION = "sRGB IEC61966-2.1"
+      PRINT = 4
+      CMYK_OPERATOR = /^(?:-?[\d.]+ ){4}[kK]$/
+
+      attr_reader :levels
+
+      def self.label(level) = LEVELS.dig(level.to_sym, :label) || level.to_s
+
+      # The Conformance for `levels` (a Symbol, an Array or nil); nil without any.
+      def self.for(levels)
+        levels = Array(levels).flatten.compact
+        levels.empty? ? nil : new(*levels)
+      end
+
+      def initialize(*levels)
+        @levels = levels.flatten.map(&:to_sym).uniq
+        unknown = @levels - LEVELS.keys
+        raise ArgumentError, "unknown conformance #{unknown.map(&:inspect).join(", ")} (use #{names})" if unknown.any?
+        raise ArgumentError, "conformance takes one PDF/A level, got #{archival.join(" and ")}" if archival.size > 1
+      end
+
+      def pdf_a? = archival.any?
+      def pdf_ua? = @levels.include?(:pdf_ua1)
+      # The PDF/A part (2 or 3), nil without one.
+      def part = archival.first && LEVELS.dig(archival.first, :part)
+
+      # What can be refused before anything is drawn: options and metadata.
+      def validate!(encrypt:, metadata:, attachments:)
+        raise ArgumentError, "PDF/A forbids encryption: drop encrypt: or the conformance level" if pdf_a? && encrypt
+        if part == 2 && attachments.any?
+          raise ArgumentError, "PDF/A-2b only embeds PDF/A files: use conformance :pdf_a3b to attach " \
+                               "#{attachments.map(&:name).join(", ")}"
+        end
+
+        missing = pdf_ua? ? %i[title lang].select { |key| metadata[key].to_s.strip.empty? } : []
+        raise ConformanceError.new(@levels, missing.map { |key| "metadata #{key}: is missing" }) if missing.any?
+      end
+
+      # What only the finished pages show. Colour that the sRGB output intent
+      # does not cover is reported; what breaks the claim outright raises.
+      def audit!(pages, resources:, warnings:)
+        cmyk(pages, resources).each { |subject| warnings << Warnings::ConformanceIssue.new(level: archival.first, subject:) }
+        issues = fields(pages) + alternatives(warnings)
+        raise ConformanceError.new(@levels, issues) if issues.any?
+      end
+
+      # The identification schemas for the XMP packet (see XMP.packet).
+      def xmp_extensions
+        extensions = {}
+        extensions[PDFA_ID] = { prefix: "pdfaid", "part" => part, "conformance" => "B" } if pdf_a?
+        extensions[PDFUA_ID] = { prefix: "pdfuaid", "part" => 1 } if pdf_ua?
+        extensions
+      end
+
+      # Schemas PDF/A has to be told about: PDF/UA's, when both are claimed.
+      def xmp_schemas = pdf_a? && pdf_ua? ? [PDFUA_SCHEMA] : []
+
+      # The catalog's entries: the sRGB output intent of a PDF/A file.
+      def catalog_entries(writer)
+        return {} unless pdf_a?
+
+        profile = writer.add(Stream.new(File.binread(ICC_PROFILE), { N: 3 }))
+        { OutputIntents: [{ Type: :OutputIntent, S: :GTS_PDFA1, DestOutputProfile: profile,
+                            OutputConditionIdentifier: TextString.new(OUTPUT_CONDITION),
+                            Info: TextString.new(OUTPUT_CONDITION) }] }
+      end
+
+      # A page's entries: PDF/UA tabs through annotations in structure order.
+      def page_entries(page) = pdf_ua? && page.annotations.any? ? { Tabs: :S } : {}
+
+      # A link annotation's entries: printable, and described for PDF/UA.
+      def annotation_entries(link)
+        entries = { F: PRINT }
+        entries[:Contents] = TextString.new(description(link)) if pdf_ua?
+        entries
+      end
+
+      private
+
+      def archival = @levels.select { |level| LEVELS.dig(level, :standard) == :pdf_a }
+      def names = LEVELS.keys.map(&:inspect).join(", ")
+
+      def description(link)
+        link[:url] || "Page #{link[:dest].page + 1}"
+      end
+
+      # Form fields draw with the standard Helvetica and ZapfDingbats, which
+      # are not embedded, and ask the viewer to regenerate appearances:
+      # neither PDF/A nor PDF/UA accepts that.
+      def fields(pages)
+        names = pages.flat_map(&:annotations).filter_map { |annotation| annotation[:widget]&.name }.uniq
+        names.map { |name| %(form field "#{name}" draws with a font that is not embedded) }
+      end
+
+      def alternatives(warnings)
+        return [] unless pdf_ua?
+
+        warnings.grep(Warnings::MissingAlt).map(&:message)
+      end
+
+      def cmyk(pages, resources)
+        return [] unless pdf_a?
+
+        images = resources.images.any? { |image| image.respond_to?(:color_space) && image.color_space == :DeviceCMYK }
+        subjects = images ? ["a CMYK image"] : []
+        pages.each_with_index do |page, index|
+          subjects << "CMYK colour on page #{index + 1}" if page.content.match?(CMYK_OPERATOR)
+        end
+        subjects
+      end
+    end
+  end
+end

data/lib/stationery/pdf/factur_x.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Stationery
+  module PDF
+    # A Factur-X / ZUGFeRD e-invoice: the invoice's Cross Industry Invoice XML
+    # embedded in a PDF/A-3b file and identified in XMP, so the one document
+    # is read by people and booked by machines.
+    #
+    # Stationery carries the XML, it does not write or validate it: `xml` is
+    # the finished document as a String, or a method name, block or callable
+    # that answers it for the document being rendered.
+    class FacturX
+      NAMESPACE = "urn:factur-x:pdfa:CrossIndustryDocument:invoice:1p0#"
+      PROFILES = { minimum: "MINIMUM", basic_wl: "BASIC WL", basic: "BASIC", en16931: "EN 16931",
+                   extended: "EXTENDED", xrechnung: "XRECHNUNG" }.freeze
+      # Profiles too small to stand for the invoice: their XML is data beside
+      # the page, not an alternative to it.
+      DATA_ONLY = %i[minimum basic_wl].freeze
+      FILENAMES = { xrechnung: "xrechnung.xml" }.freeze
+      DEFAULT_FILENAME = "factur-x.xml"
+      DESCRIPTION = "Factur-X Invoice"
+      ROOTS = ["<?xml", "<rsm:CrossIndustryInvoice"].freeze
+      SCHEMA = {
+        name: "Factur-X PDFA Extension Schema", uri: NAMESPACE, prefix: "fx",
+        properties: [
+          { name: "DocumentFileName", type: "Text", category: "external",
+            description: "The name of the embedded XML document" },
+          { name: "DocumentType", type: "Text", category: "external",
+            description: "The type of the hybrid document in capital letters, e.g. INVOICE or ORDER" },
+          { name: "Version", type: "Text", category: "external",
+            description: "The actual version of the standard applying to the embedded XML document" },
+          { name: "ConformanceLevel", type: "Text", category: "external",
+            description: "The conformance level of the embedded XML document" }
+        ].freeze
+      }.freeze
+
+      attr_reader :xml, :profile, :filename, :version
+
+      # The invoice for `spec` (`{ xml:, profile:, filename:, version:,
+      # relationship: }`, as `factur_x` and `to_pdf(factur_x:)` take it)
+      # resolved for `document`; nil without a spec.
+      def self.for(spec, document)
+        return unless spec
+
+        spec = spec.to_h.transform_keys(&:to_sym)
+        new(resolve(spec[:xml], document), **spec.except(:xml))
+      end
+
+      def self.resolve(xml, document)
+        case xml
+        when Symbol then document.send(xml)
+        when Proc then xml.arity.zero? ? document.instance_exec(&xml) : xml.call(document)
+        else xml.respond_to?(:call) ? xml.call(document) : xml
+        end
+      end
+
+      def self.profile(name)
+        name = name.to_s.downcase.to_sym
+        return name if PROFILES.key?(name)
+
+        raise ArgumentError, "unknown Factur-X profile #{name.inspect} (use #{PROFILES.keys.map(&:inspect).join(", ")})"
+      end
+
+      def self.invoice?(xml) = xml.is_a?(String) && xml.delete_prefix("").lstrip.start_with?(*ROOTS)
+
+      def initialize(xml, profile: :en16931, filename: nil, version: "1.0", relationship: nil)
+        @profile = self.class.profile(profile)
+        unless self.class.invoice?(xml)
+          raise ArgumentError, "factur_x needs the invoice XML (a String starting with #{ROOTS.join(" or ")}), " \
+                               "#{got(xml)}"
+        end
+
+        @xml = xml
+        @filename = (filename || FILENAMES.fetch(@profile, DEFAULT_FILENAME)).to_s
+        @version = version.to_s
+        @relationship = relationship || (DATA_ONLY.include?(@profile) ? :data : :alternative)
+      end
+
+      # The fx:ConformanceLevel of the profile ("EN 16931").
+      def level = PROFILES.fetch(@profile)
+
+      # The declared conformance levels with the PDF/A-3b the invoice needs.
+      def conformance(levels)
+        levels = Array(levels).flatten.compact.map(&:to_sym)
+        if levels.include?(:pdf_a2b)
+          raise ArgumentError, "Factur-X embeds its XML, which needs PDF/A-3b: drop conformance :pdf_a2b"
+        end
+
+        levels.include?(:pdf_a3b) ? levels : levels + [:pdf_a3b]
+      end
+
+      # The XML as the file to embed, stamped `at` (its /ModDate).
+      def attachment(at: Time.now)
+        Attachments.build(@filename, @xml, mime: "text/xml", description: DESCRIPTION, relationship: @relationship,
+                                           modified_at: at)
+      end
+
+      # The invoice's identification for the XMP packet (see XMP.packet).
+      def xmp_extensions
+        { NAMESPACE => { prefix: "fx", "DocumentType" => "INVOICE", "DocumentFileName" => @filename,
+                         "Version" => @version, "ConformanceLevel" => level } }
+      end
+
+      # The description of the `fx` schema PDF/A asks for.
+      def xmp_schema = SCHEMA
+
+      private
+
+      def got(xml)
+        return "got #{xml.nil? ? "nil" : "a #{xml.class}"}" unless xml.is_a?(String)
+        return "got an empty String" if xml.strip.empty?
+
+        "got #{xml[0, 40].inspect}"
+      end
+    end
+  end
+end

data/lib/stationery/pdf/icc/LICENSE.md

@@ -0,0 +1,14 @@
+# sRGB2014.icc
+
+`sRGB2014.icc` is the ICC's sRGB v2 profile ("sRGB2014", copyright International Color
+Consortium, 2015), downloaded unmodified from
+<https://registry.color.org/rgb-registry/profiles/sRGB2014.icc>
+(SHA-256 `384b832de3412066743b52a75ee906b6fb9fb8d9e09e936fc2c43223815c6e0a`).
+Stationery embeds it as the output intent of PDF/A documents.
+
+The ICC's terms for profiles it owns (<https://www.color.org/profiles2.xalter#license>):
+
+> This profile is made available by the International Color Consortium, and may be copied,
+> distributed, embedded, made, used, and sold without restriction. Altered versions of this
+> profile shall have the original identification and copyright information removed and shall
+> not be misrepresented as the original profile.

data/lib/stationery/pdf/page_labels.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Stationery
+  module PDF
+    # The /PageLabels number tree: how viewers name pages ("i", "ii", "1",
+    # "A-1"). A spec maps a 1-based first page to the range starting there:
+    #
+    #   { 1 => { style: :roman_lower }, 3 => { style: :decimal, start: 1, prefix: "A-" } }
+    #
+    # Styles are :decimal, :roman, :roman_lower, :alpha, :alpha_lower or nil
+    # (prefix only). Pages before the first range have no label; viewers show
+    # their physical number.
+    module PageLabels
+      STYLES = { decimal: :D, roman: :R, roman_lower: :r, alpha: :A, alpha_lower: :a }.freeze
+      NUMERALS = { D: :decimal, R: :upper_roman, r: :roman, A: :upper_alpha, a: :alpha }.freeze
+      KEYS = %i[style start prefix].freeze
+
+      module_function
+
+      # The number tree dictionary for a spec, or nil for none.
+      def entries(spec)
+        return if spec.nil? || spec.empty?
+
+        nums = spec.sort_by { |page, _| validate_page(page) }.flat_map do |page, range|
+          [page - 1, entry(page, range)]
+        end
+        { Nums: nums }
+      end
+
+      # The label of each of `count` pages from a /Nums array (as read back).
+      def labels(nums, count)
+        ranges = nums.each_slice(2).to_a
+        Array.new(count) do |index|
+          start, dict = ranges.reverse.find { |from, _| from <= index }
+          dict && label(dict, index - start)
+        end
+      end
+
+      def validate_page(page)
+        return page if page.is_a?(Integer) && page >= 1
+
+        raise ArgumentError, "page labels start at page 1, not page #{page.inspect}"
+      end
+
+      def entry(page, range)
+        unknown = range.keys - KEYS
+        raise ArgumentError, "unknown page label option #{unknown.first.inspect} for page #{page}" if unknown.any?
+
+        style = range[:style]
+        raise ArgumentError, "unknown page label style #{style.inspect}" unless style.nil? || STYLES.key?(style)
+
+        start = range[:start]
+        if start && !(start.is_a?(Integer) && start >= 1)
+          raise ArgumentError, "page label start #{start.inspect} for page #{page} must be 1 or more"
+        end
+
+        entry = {}
+        entry[:S] = STYLES[style] if style
+        entry[:St] = start if start
+        entry[:P] = TextString.new(range[:prefix].to_s) if range[:prefix]
+        entry
+      end
+
+      def label(dict, offset)
+        numeral = NUMERALS[dict[:S]&.to_sym]
+        number = (dict[:St] || 1) + offset
+        "#{dict[:P]}#{ListMarkers.numeral(numeral, number) if numeral}"
+      end
+    end
+  end
+end

data/lib/stationery/pdf/stream.rb

@@ -5,15 +5,17 @@ require "zlib"
 module Stationery
   module PDF
     # A stream object. Data is Flate-compressed unless the dictionary already
-    # names a filter (JPEG's DCTDecode, or PNG data that is already zlib).
+    # names a filter (JPEG's DCTDecode, or PNG data that is already zlib) or
+    # `compress: false` asks for it plain (XMP metadata, which PDF/A readers
+    # scan for without decoding).
     class Stream
       attr_reader :dictionary, :data
 
-      def initialize(data, dictionary = {})
+      def initialize(data, dictionary = {}, compress: !dictionary.key?(:Filter))
         data = data.b
         dictionary = dictionary.dup
 
-        unless dictionary.key?(:Filter)
+        if compress
           data = Zlib::Deflate.deflate(data)
           dictionary[:Filter] = :FlateDecode
         end

data/lib/stationery/pdf/xmp.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module Stationery
+  module PDF
+    # The XMP metadata packet (ISO 16684-1) mirroring the document info:
+    # Dublin Core title, creator, description, subject and language, the
+    # `xmp:` dates and creator tool, and `pdf:` producer and keywords. Later
+    # identification schemas (PDF/A, PDF/UA, Factur-X) go in `extensions:`.
+    #
+    # The packet is deterministic for the same info and time: no instance
+    # ids, so two renders of one document are byte-identical.
+    module XMP
+      PACKET_ID = "W5M0MpCehiHzreSzNTczkc9d"
+      PADDING = "#{" " * 63}\n" * 32 # 2 KB of whitespace, as the spec suggests
+      DC = "http://purl.org/dc/elements/1.1/"
+      XMP_NS = "http://ns.adobe.com/xap/1.0/"
+      PDF_NS = "http://ns.adobe.com/pdf/1.3/"
+      RDF = "http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+      PDFA_EXTENSION = { "pdfaExtension" => "http://www.aiim.org/pdfa/ns/extension/",
+                         "pdfaSchema" => "http://www.aiim.org/pdfa/ns/schema#",
+                         "pdfaProperty" => "http://www.aiim.org/pdfa/ns/property#" }.freeze
+
+      module_function
+
+      # `info` is the Info dictionary's keys (`:Title`, `:Author`, `:Subject`,
+      # `:Keywords`, `:Creator`, `:Producer`), `lang` the catalog language,
+      # `time` the creation instant, and `extensions` further schemas as
+      # `{ namespace_uri => { prefix: "pdfaid", "part" => 3, "conformance" => "B" } }`:
+      # each becomes one `rdf:Description`; Array values become an `rdf:Bag`.
+      # `schemas` describes extension schemas PDF/A does not know by itself:
+      # `[{ name:, uri:, prefix:, properties: [{ name:, type:, category:, description: }] }]`.
+      def packet(info: {}, lang: nil, time: Time.now, extensions: {}, schemas: [])
+        descriptions = [dublin_core(info, lang), xmp_schema(info, time), pdf_schema(info)]
+        descriptions << extension_schemas(schemas)
+        descriptions.concat(extensions.map { |uri, values| extension(uri, values) })
+        body = <<~XML.gsub(/^ *\n/, "")
+          <?xpacket begin="" id="#{PACKET_ID}"?>
+          <x:xmpmeta xmlns:x="adobe:ns:meta/">
+           <rdf:RDF xmlns:rdf="#{RDF}">
+          #{descriptions.compact.join("\n")}
+           </rdf:RDF>
+          </x:xmpmeta>
+        XML
+        "#{body}#{PADDING}<?xpacket end=\"w\"?>\n"
+      end
+
+      def escape(value)
+        value.to_s.gsub("&", "&amp;").gsub("<", "&lt;").gsub(">", "&gt;").gsub('"', "&quot;")
+      end
+
+      def dublin_core(info, lang)
+        keywords = info[:Keywords].to_s.split(/,\s*/).reject(&:empty?)
+        elements = [
+          alt("dc:title", info[:Title]),
+          seq("dc:creator", info[:Author]),
+          alt("dc:description", info[:Subject]),
+          bag("dc:subject", keywords),
+          bag("dc:language", lang && [lang])
+        ]
+        description(DC, "dc", elements)
+      end
+
+      def xmp_schema(info, time)
+        stamp = time.utc.strftime("%Y-%m-%dT%H:%M:%SZ")
+        elements = [
+          element("xmp:CreateDate", stamp), element("xmp:ModifyDate", stamp), element("xmp:MetadataDate", stamp),
+          element("xmp:CreatorTool", info[:Creator])
+        ]
+        description(XMP_NS, "xmp", elements)
+      end
+
+      def pdf_schema(info)
+        description(PDF_NS, "pdf", [element("pdf:Producer", info[:Producer]), element("pdf:Keywords", info[:Keywords])])
+      end
+
+      def extension(uri, values)
+        prefix = values.fetch(:prefix) { raise ArgumentError, "XMP extension #{uri} needs a :prefix" }
+        elements = values.except(:prefix).map do |name, value|
+          value.is_a?(Array) ? bag("#{prefix}:#{name}", value) : element("#{prefix}:#{name}", value)
+        end
+        description(uri, prefix, elements)
+      end
+
+      # The PDF/A extension schema container describing each of `schemas`.
+      def extension_schemas(schemas)
+        return if schemas.empty?
+
+        namespaces = PDFA_EXTENSION.map { |prefix, uri| %(xmlns:#{prefix}="#{uri}") }.join(" ")
+        items = schemas.map { |schema| "  #{schema_item(schema)}\n" }.join
+        <<~XML.chomp.gsub(/^/, "  ")
+          <rdf:Description rdf:about="" #{namespaces}>
+           <pdfaExtension:schemas><rdf:Bag>
+          #{items.chomp}
+           </rdf:Bag></pdfaExtension:schemas>
+          </rdf:Description>
+        XML
+      end
+
+      def schema_item(schema)
+        properties = schema.fetch(:properties).map do |property|
+          resource("pdfaProperty", name: property.fetch(:name), valueType: property.fetch(:type),
+                                   category: property.fetch(:category), description: property.fetch(:description))
+        end
+        head = { schema: schema.fetch(:name), namespaceURI: schema.fetch(:uri), prefix: schema.fetch(:prefix) }
+        resource("pdfaSchema", **head) do
+          "<pdfaSchema:property><rdf:Seq>#{properties.join}</rdf:Seq></pdfaSchema:property>"
+        end
+      end
+
+      def resource(prefix, **values)
+        elements = values.map { |name, value| element("#{prefix}:#{name}", value) }.join
+        %(<rdf:li rdf:parseType="Resource">#{elements}#{yield if block_given?}</rdf:li>)
+      end
+
+      def description(uri, prefix, elements)
+        elements = elements.compact
+        return if elements.empty?
+
+        "  <rdf:Description rdf:about=\"\" xmlns:#{prefix}=\"#{escape(uri)}\">\n" \
+          "#{elements.map { |line| "   #{line}\n" }.join}  </rdf:Description>"
+      end
+
+      def element(name, value)
+        return if blank?(value)
+
+        "<#{name}>#{escape(value)}</#{name}>"
+      end
+
+      def alt(name, value)
+        return if blank?(value)
+
+        "<#{name}><rdf:Alt><rdf:li xml:lang=\"x-default\">#{escape(value)}</rdf:li></rdf:Alt></#{name}>"
+      end
+
+      def seq(name, value) = list(name, "rdf:Seq", value)
+      def bag(name, value) = list(name, "rdf:Bag", value)
+
+      def list(name, container, values)
+        values = Array(values).reject { |value| blank?(value) }
+        return if values.empty?
+
+        items = values.map { |value| "<rdf:li>#{escape(value)}</rdf:li>" }.join
+        "<#{name}><#{container}>#{items}</#{container}></#{name}>"
+      end
+
+      def blank?(value) = value.nil? || value.to_s.empty?
+    end
+  end
+end

data/lib/stationery/resources.rb

@@ -11,6 +11,9 @@ module Stationery
       @shadings = {}
     end
 
+    # Every image drawn so far.
+    def images = @images.keys
+
     def font(font)
       @fonts[font] ||= :"F#{@fonts.size + 1}"
     end

data/lib/stationery/svg/clip_path.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Stationery
+  module SVG
+    # Turns `clip-path: url(#id)` into the Region an element is painted in.
+    # The shapes of the clipPath (and the shapes its `use` children refer to)
+    # are outlined in the user space of the clipped element, under the clip
+    # path's own transform and theirs; `clipPathUnits="objectBoundingBox"`
+    # scales them to the element's box. They join into one clipping path, so
+    # overlapping shapes wound in opposite directions cancel where they
+    # overlap. A clip path's own clip-path is the region around it. Text in
+    # a clip path is skipped and reported.
+    class ClipPath
+      OUTLINED = (Shapes::NAMES + %w[text]).freeze
+
+      def initialize(ids, walker)
+        @ids = ids
+        @walker = walker
+      end
+
+      # The Region for `element`, drawn with `style`; nil without such a clip
+      # path, when the element is painted unclipped.
+      def region(id, element, style, seen = [])
+        clip = @ids[id]
+        return @walker.issue("clip-path: ##{id} not found") unless clip&.name == "clipPath"
+        return @walker.issue("clip-path: circular reference ##{id}") if seen.include?(id)
+
+        base = user_space(clip, element, style) or return Region::EMPTY
+        own = base.child(clip)
+        outlines = clip.children.grep(Parser::Element).filter_map { |child| outline(child, own.child(child), id) }
+        outer = own.clip_path && region(own.clip_path, element, style, seen + [id])
+        Region.new(outlines.map(&:first), outlines.any?(&:last), outer)
+      end
+
+      private
+
+      # The style the clip path's content starts from; nil when the units
+      # are the element's box and it has none.
+      def user_space(clip, element, style)
+        space = style.at(style.matrix, Style::DEFAULTS)
+        return space unless clip.attributes["clipPathUnits"] == "objectBoundingBox"
+
+        x, y, width, height = @walker.box(element, style)
+        space.transformed([width, 0, 0, height, x, y]) if x
+      end
+
+      # [part, even-odd?] for a child that outlines something.
+      def outline(child, style, id)
+        return unless style.displayed? && style.visible?
+
+        case child.name
+        when "use" then used(child, style, id)
+        when "text" then @walker.issue("clipPath ##{id}: text")
+        when *Shapes::NAMES then [Region::Part.new(style.matrix, Region::Shape.new(child)), style.clip_even_odd?]
+        end
+      end
+
+      # A use in a clip path refers to a shape or a text, not to a group.
+      def used(child, style, id)
+        attributes = child.attributes
+        target = @ids[(attributes["href"] || attributes["xlink:href"]).to_s[/\A#(.+)/, 1]]
+        return unless target && OUTLINED.include?(target.name)
+
+        placed = style.transformed([1, 0, 0, 1, Shapes.f(attributes, "x"), Shapes.f(attributes, "y")])
+        outline(target, placed.child(target), id)
+      end
+    end
+  end
+end