prawn-accessibility 1.0.0

data/lib/prawn/accessibility/structure_tree.rb

@@ -0,0 +1,275 @@
+# frozen_string_literal: true
+
+module PDF
+  module Core
+    # Manages the PDF structure tree for tagged/accessible PDFs.
+    #
+    # The structure tree provides the logical structure of a document,
+    # mapping marked content sequences in page content streams to
+    # structure elements (headings, paragraphs, tables, etc.).
+    #
+    # PDF spec references: Section 14.7 (Logical Structure)
+    #
+    # @api private
+    class StructureTree
+      # @return [PDF::Core::Renderer] owning renderer
+      attr_reader :renderer
+
+      # @return [PDF::Core::Reference] StructTreeRoot indirect object
+      attr_reader :root_ref
+
+      # @return [PDF::Core::Reference] Document-level structure element
+      attr_reader :document_elem_ref
+
+      # @return [Array<Hash>] all structure elements created
+      attr_reader :elements
+
+      # @return [Hash{Integer => Array}] page StructParents index => array of
+      #   structure element refs for marked content on that page
+      attr_reader :parent_tree_map
+
+      # @return [Integer] next available MCID for the current page
+      attr_reader :next_mcid
+
+      # @return [Array<PDF::Core::Reference>] stack of open structure elements
+      attr_reader :element_stack
+
+      # @param renderer [PDF::Core::Renderer]
+      def initialize(renderer)
+        @renderer = renderer
+        @elements = []
+        @parent_tree_map = {}
+        @next_mcid = 0
+        @element_stack = []
+        @page_mcid_map = {} # page_ref_id => next mcid for that page
+        @root_ref = nil
+        @document_elem_ref = nil
+      end
+
+      # Allocate the next MCID for the current page and track it.
+      #
+      # @return [Integer] the allocated MCID
+      def allocate_mcid
+        page = renderer.state.page
+        page_id = page.dictionary.identifier
+
+        @page_mcid_map[page_id] ||= 0
+        mcid = @page_mcid_map[page_id]
+        @page_mcid_map[page_id] += 1
+
+        mcid
+      end
+
+      # Add a structure element as a child of the current open element
+      # (or the document element if none is open).
+      #
+      # @param tag [Symbol] structure type (e.g., :P, :H1, :Table, :TD)
+      # @param attributes [Hash] additional attributes for the structure element
+      # @option attributes [String] :Alt alternative text (for Figure, Formula)
+      # @option attributes [String] :ActualText replacement text for screen
+      #   readers (e.g., "required" instead of reading "*")
+      # @option attributes [String] :Lang language tag
+      # @option attributes [Symbol] :Scope TH scope (:Column, :Row, :Both)
+      # @return [PDF::Core::Reference] the structure element reference
+      def add_element(tag, attributes = {})
+        parent_ref = current_element || document_element
+
+        elem_data = {
+          Type: :StructElem,
+          S: tag,
+          P: parent_ref,
+          K: [],
+        }
+
+        elem_data[:Alt] = attributes[:Alt] if attributes[:Alt]
+        elem_data[:ActualText] = attributes[:ActualText] if attributes[:ActualText]
+        elem_data[:Lang] = attributes[:Lang] if attributes[:Lang]
+
+        if attributes[:Scope]
+          elem_data[:A] = {
+            O: :Table,
+            Scope: attributes[:Scope],
+          }
+        end
+
+        elem_ref = renderer.ref!(elem_data)
+        @elements << elem_ref
+
+        # Add as child of parent
+        parent_data = renderer.deref(parent_ref)
+        parent_data[:K] << elem_ref
+
+        elem_ref
+      end
+
+      # Begin a structure element scope. Content rendered inside will be
+      # children of this element.
+      #
+      # @param tag [Symbol] structure type
+      # @param attributes [Hash] additional attributes
+      # @return [PDF::Core::Reference] the opened structure element
+      def begin_element(tag, attributes = {})
+        elem_ref = add_element(tag, attributes)
+        @element_stack.push(elem_ref)
+        elem_ref
+      end
+
+      # End the current structure element scope.
+      #
+      # @return [PDF::Core::Reference] the closed structure element
+      def end_element
+        @element_stack.pop
+      end
+
+      # Add marked content to the current structure element.
+      # This allocates an MCID, records the mapping, and emits BDC/EMC
+      # operators around the yielded block.
+      #
+      # @param tag [Symbol] marked content tag (e.g., :P, :Span)
+      # @param struct_elem_ref [PDF::Core::Reference, nil] the structure element
+      #   this content belongs to. If nil, uses current_element.
+      # @yield content to render inside the marked content sequence
+      # @return [void]
+      def mark_content(tag, struct_elem_ref: nil)
+        elem_ref = struct_elem_ref || current_element || document_element
+        mcid = allocate_mcid
+        page = renderer.state.page
+        page_ref = page.dictionary
+
+        # Record in parent tree map
+        page_struct_parents = page_struct_parents_index(page_ref)
+        @parent_tree_map[page_struct_parents] ||= []
+
+        # Add marked content reference to the structure element's K array
+        mcr = { Type: :MCR, MCID: mcid, Pg: page_ref }
+        elem_data = renderer.deref(elem_ref)
+        elem_data[:K] << mcr
+
+        # Track which struct element owns this MCID on this page
+        @parent_tree_map[page_struct_parents][mcid] = elem_ref
+
+        # Emit BDC/EMC in content stream
+        renderer.begin_marked_content_with_properties(tag, { MCID: mcid })
+        yield if block_given?
+        renderer.end_marked_content
+      end
+
+      # Mark content as an artifact (decorative, not read by screen readers).
+      #
+      # @param artifact_type [Symbol, nil] optional artifact type
+      #   (:Pagination, :Layout, :Page, :Background)
+      # @yield content to render as artifact
+      # @return [void]
+      def mark_artifact(artifact_type: nil)
+        if artifact_type
+          renderer.begin_marked_content_with_properties(
+            :Artifact, { Type: artifact_type },
+          )
+        else
+          renderer.begin_marked_content(:Artifact)
+        end
+        yield if block_given?
+        renderer.end_marked_content
+      end
+
+      # Finalize the structure tree before rendering. Called via
+      # before_render callback.
+      #
+      # Builds the StructTreeRoot, ParentTree, and wires everything
+      # into the Catalog.
+      #
+      # @return [void]
+      def finalize!
+        return if @elements.empty? && @parent_tree_map.empty?
+
+        build_root
+        build_parent_tree
+        assign_struct_parents_to_pages
+        attach_to_catalog
+      end
+
+      private
+
+      # The current open structure element, or nil if none.
+      #
+      # @return [PDF::Core::Reference, nil]
+      def current_element
+        @element_stack.last
+      end
+
+      # Get or create the Document-level structure element.
+      #
+      # @return [PDF::Core::Reference]
+      def document_element
+        return @document_elem_ref if @document_elem_ref
+
+        @document_elem_ref = renderer.ref!(
+          Type: :StructElem,
+          S: :Document,
+          P: nil, # will be set to StructTreeRoot in finalize!
+          K: [],
+        )
+        @elements << @document_elem_ref
+        @document_elem_ref
+      end
+
+      # Get or assign a StructParents index for a page.
+      #
+      # @param page_ref [PDF::Core::Reference] page dictionary reference
+      # @return [Integer] the StructParents index
+      def page_struct_parents_index(page_ref)
+        page_ref.data[:StructParents] ||= @parent_tree_map.size
+        page_ref.data[:StructParents]
+      end
+
+      # Build the StructTreeRoot object.
+      #
+      # @return [void]
+      def build_root
+        @root_ref = renderer.ref!(
+          Type: :StructTreeRoot,
+          K: document_element,
+          ParentTree: nil, # set in build_parent_tree
+        )
+
+        # Point Document element's parent to the root
+        doc_data = renderer.deref(@document_elem_ref)
+        doc_data[:P] = @root_ref
+      end
+
+      # Build the ParentTree (a number tree mapping StructParents indices
+      # to arrays of structure element references).
+      #
+      # @return [void]
+      def build_parent_tree
+        # ParentTree is a number tree. For simplicity, use a flat Nums array
+        # since most documents won't have enough pages to need a balanced tree.
+        nums = []
+        @parent_tree_map.sort_by { |k, _| k }.each do |index, elem_array|
+          nums << index
+          nums << renderer.ref!(elem_array)
+        end
+
+        parent_tree_ref = renderer.ref!(Type: :ParentTree, Nums: nums)
+        root_data = renderer.deref(@root_ref)
+        root_data[:ParentTree] = parent_tree_ref
+      end
+
+      # Ensure each page that has marked content has a StructParents entry.
+      # (Already handled lazily in page_struct_parents_index, but verify.)
+      #
+      # @return [void]
+      def assign_struct_parents_to_pages
+        # Already assigned lazily when mark_content is called.
+        # This method exists as a hook for any additional finalization.
+      end
+
+      # Wire the StructTreeRoot into the document Catalog.
+      #
+      # @return [void]
+      def attach_to_catalog
+        renderer.state.store.root.data[:StructTreeRoot] = @root_ref
+      end
+    end
+  end
+end

data/lib/prawn/accessibility/table.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+# Table accessibility patches. This file is only loaded when Prawn::Table is
+# already defined (see prawn/accessibility.rb), so requiring prawn-accessibility
+# without prawn-table installed is safe.
+
+unless defined?(Prawn::Table)
+  raise 'prawn/accessibility/table requires prawn-table to be loaded first'
+end
+
+module Prawn
+  module Accessibility
+    # Patches applied to the published +prawn-table+ gem so that tables emit
+    # +<Table>+/+<TR>+/+<TH>+/+<TD>+ structure elements when the owning document
+    # is tagged. Untagged tables render exactly as upstream (via +super+).
+    #
+    # @api private
+    module TablePatch
+      # Prepended onto {Prawn::Table#initialize} to flag header cells after
+      # the table has been built and positioned.
+      #
+      # @api private
+      module TableInstancePatch
+        def initialize(*args, &block)
+          super
+          mark_header_cells
+        end
+
+        # Draws the table, wrapping it in a +<Table>+ structure element when
+        # the document is tagged.
+        def draw
+          if @pdf.respond_to?(:tagged?) && @pdf.tagged?
+            @pdf.structure_container(:Table) { super() }
+          else
+            super
+          end
+        end
+
+        # Marks cells in header rows as header cells for accessibility.
+        #
+        # @return [void]
+        def mark_header_cells
+          n = number_of_header_rows
+          return if n.zero?
+
+          @cells.each do |cell|
+            cell.is_header_cell = true if cell.row < n
+          end
+        end
+      end
+
+      # Prepended onto the {Prawn::Table::Cell} singleton so
+      # <tt>Cell.draw_cells</tt> emits row/cell structure tags in tagged mode.
+      #
+      # @api private
+      module CellClassPatch
+        def draw_cells(cells)
+          return super if cells.empty?
+
+          first_entry = cells.first
+          first_cell = first_entry.is_a?(Array) ? first_entry[0] : first_entry
+          pdf = first_cell.instance_variable_get(:@pdf)
+          tagged = pdf.respond_to?(:tagged?) && pdf.tagged?
+
+          return super unless tagged
+
+          # Phase 1: backgrounds (decorative — artifact in tagged mode)
+          pdf.artifact(type: :Layout) do
+            cells.each do |cell, pt|
+              cell.set_width_constraints
+              cell.draw_background(pt)
+            end
+          end
+
+          # Phase 2: borders and content, wrapped in TR/TH/TD structure
+          draw_cells_tagged(cells, pdf)
+        end
+
+        # Draw cells with accessibility structure tags (TR, TH, TD).
+        #
+        # @api private
+        def draw_cells_tagged(cells, pdf)
+          # Group cells by row for TR wrapping
+          rows = cells.group_by { |cell, _pt| cell.row }
+
+          rows.sort_by { |row_num, _| row_num }.each do |_row_num, row_cells|
+            pdf.structure_container(:TR) do
+              row_cells.each do |cell, pt|
+                # Skip span dummy cells — the master cell handles drawing
+                next if cell.is_a?(Prawn::Table::Cell::SpanDummy)
+
+                # Borders are decorative
+                pdf.artifact(type: :Layout) { cell.draw_borders(pt) }
+
+                # Content gets TH or TD tag
+                tag = cell.header? ? :TH : :TD
+                attrs = {}
+                attrs[:Scope] = :Column if tag == :TH
+
+                pdf.structure(tag, attrs) do
+                  cell.draw_content_only(pt)
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+# --- Additive re-open of Prawn::Table::Cell ---------------------------------
+
+module Prawn
+  class Table
+    class Cell
+      # Whether this cell is a header cell (TH) for accessibility. Set
+      # automatically for cells in header rows when the table has
+      # <tt>header: true</tt>.
+      attr_accessor :is_header_cell
+
+      # Whether this cell is a header cell.
+      #
+      # @return [Boolean]
+      def header?
+        !!@is_header_cell
+      end
+
+      # Draws only the cell content (no borders or background). Used by the
+      # tagged PDF rendering path where borders are drawn separately as
+      # artifacts.
+      #
+      # @api private
+      def draw_content_only(pt)
+        draw_bounded_content(pt)
+      end
+    end
+  end
+end
+
+Prawn::Table.prepend(Prawn::Accessibility::TablePatch::TableInstancePatch)
+Prawn::Table::Cell.singleton_class.prepend(
+  Prawn::Accessibility::TablePatch::CellClassPatch,
+)

data/lib/prawn/accessibility/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Prawn
+  module Accessibility
+    # Gem version. Follows Semantic Versioning (https://semver.org).
+    VERSION = '1.0.0'
+  end
+end

data/lib/prawn/accessibility.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative 'accessibility/version'
+require_relative 'accessibility/document'
+
+# prawn-table support is optional. If the gem is installed, load it and apply
+# the table tagging patches; otherwise carry on without table support.
+begin
+  require 'prawn/table'
+rescue LoadError
+  # prawn-table is not available; table tagging is disabled.
+end
+
+require_relative 'accessibility/table' if defined?(Prawn::Table)

data/lib/prawn-accessibility.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Conventional entry point matching the gem name (`require 'prawn-accessibility'`).
+require_relative 'prawn/accessibility'

metadata

@@ -0,0 +1,97 @@
+--- !ruby/object:Gem::Specification
+name: prawn-accessibility
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Mes Amis
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: pdf-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.10'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.10'
+- !ruby/object:Gem::Dependency
+  name: prawn
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.5'
+description: |
+  prawn-accessibility layers tagged-PDF support onto the published prawn,
+  pdf-core, and (optionally) prawn-table gems. It adds a high-level API for
+  marking document structure — headings, paragraphs, figures, tables, and
+  artifacts — so Prawn can produce Section 508 / WCAG accessible PDFs.
+
+  The behavior originates from the stalled upstream pull requests
+  prawnpdf/pdf-core#67, prawnpdf/prawn#1391, and prawnpdf/prawn-table#164,
+  repackaged here as a standalone gem that patches the released libraries via
+  `prepend`/additive re-opens rather than forking them.
+email:
+- craig@monami.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- COPYING
+- GPLv2
+- GPLv3
+- LICENSE
+- README.md
+- lib/prawn-accessibility.rb
+- lib/prawn/accessibility.rb
+- lib/prawn/accessibility/document.rb
+- lib/prawn/accessibility/marked_content.rb
+- lib/prawn/accessibility/pdf_core.rb
+- lib/prawn/accessibility/structure_tree.rb
+- lib/prawn/accessibility/table.rb
+- lib/prawn/accessibility/version.rb
+homepage: https://github.com/mes-amis/prawn-accessibility
+licenses:
+- Nonstandard
+- GPL-2.0-only
+- GPL-3.0-only
+metadata:
+  homepage_uri: https://github.com/mes-amis/prawn-accessibility
+  source_code_uri: https://github.com/mes-amis/prawn-accessibility
+  changelog_uri: https://github.com/mes-amis/prawn-accessibility/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Tagged PDF (Section 508 / WCAG) accessibility for Prawn.
+test_files: []