prawn-accessibility 1.0.0

data/LICENSE

@@ -0,0 +1,58 @@
+prawn-accessibility is copyrighted free software produced by Mes Amis along with
+community contributions. It derives from and is distributed under the same terms
+as Prawn (copyright Gregory Brown along with community contributions). See git
+log for authorship information.
+
+Licensing terms follow:
+
+You can redistribute prawn-accessibility and/or modify it under either the terms
+of the GPLv2 or GPLv3 (see GPLv2 and GPLv3 files), or the conditions below:
+
+  1. You may make and give away verbatim copies of the source form of the
+     software without restriction, provided that you duplicate all of the
+     original copyright notices and associated disclaimers.
+
+  2. You may modify your copy of the software in any way, provided that
+     you do at least ONE of the following:
+
+       a) place your modifications in the Public Domain or otherwise
+          make them Freely Available, such as by posting said
+    modifications to Usenet or an equivalent medium, or by allowing
+    the author to include your modifications in the software.
+
+       b) use the modified software only within your corporation or
+          organization.
+
+       c) rename any non-standard executables so the names do not conflict
+    with standard executables, which must also be provided.
+
+       d) make other distribution arrangements with the author.
+
+  3. You may distribute the software in object code or executable
+     form, provided that you do at least ONE of the following:
+
+       a) distribute the executables and library files of the software,
+    together with instructions (in the manual page or equivalent)
+    on where to get the original distribution.
+
+       b) accompany the distribution with the machine-readable source of
+    the software.
+
+       c) give non-standard executables non-standard names, with
+          instructions on where to get the original software distribution.
+
+       d) make other distribution arrangements with the author.
+
+  4. You may modify and include the part of the software into any other
+     software (possibly commercial).
+
+  5. The scripts and library files supplied as input to or produced as
+     output from the software do not automatically fall under the
+     copyright of the software, but belong to whomever generated them,
+     and may be sold commercially, and may be aggregated with this
+     software.
+
+  6. THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
+     IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+     WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+     PURPOSE.

data/README.md

@@ -0,0 +1,89 @@
+# prawn-accessibility
+
+[![CI](https://github.com/mes-amis/prawn-accessibility/actions/workflows/ci.yml/badge.svg)](https://github.com/mes-amis/prawn-accessibility/actions/workflows/ci.yml)
+
+Tagged-PDF (GSA **Section 508** / **WCAG**) accessibility for [Prawn](https://github.com/prawnpdf/prawn).
+
+`prawn-accessibility` adds a high-level API for marking document structure —
+headings, paragraphs, figures, tables, and decorative artifacts — so Prawn can
+produce accessible, tagged PDFs that screen readers can navigate.
+
+It layers on top of the **published** `prawn`, `pdf-core`, and (optionally)
+`prawn-table` gems using `prepend` and additive re-opens — it does **not** fork
+them. When you don't opt in (`marked: true`), output is byte-for-byte identical
+to stock Prawn.
+
+## Installation
+
+```ruby
+# Gemfile
+gem 'prawn-accessibility'
+```
+
+`prawn` and `pdf-core` are pulled in automatically. Table tagging activates
+automatically **if `prawn-table` is also in your bundle** — it is not a required
+dependency:
+
+```ruby
+gem 'prawn-table' # optional; enables <Table>/<TR>/<TH>/<TD> tagging
+```
+
+## Usage
+
+```ruby
+require 'prawn-accessibility'
+
+pdf = Prawn::Document.new(marked: true, language: 'en-US')
+
+pdf.heading(1, 'Annual Report')                                   # <H1>
+pdf.paragraph('Body text that a screen reader will read aloud.')  # <P>
+
+pdf.structure(:Span, ActualText: 'required') { pdf.text('*') }    # replacement text
+pdf.figure(alt_text: 'Company logo') { pdf.image('logo.png') }    # <Figure> with /Alt
+
+pdf.artifact(type: :Pagination) { pdf.text('Page 1') }            # decorative, not read
+
+# Tables auto-tag when the document is tagged:
+pdf.table([['Name', 'Age'], ['Alice', '30']], header: true)       # <Table>/<TR>/<TH>/<TD>
+
+pdf.render_file('report.pdf')
+```
+
+### API
+
+| Method | Emits |
+|---|---|
+| `pdf.tagged?` | whether the document is in tagged mode |
+| `pdf.structure(tag, attrs) { … }` | a structure element wrapping marked content |
+| `pdf.structure_container(tag, attrs) { … }` | a container whose children mark themselves |
+| `pdf.artifact(type:) { … }` | decorative content (ignored by screen readers) |
+| `pdf.heading(level, text, opts)` | `<H1>`–`<H6>` |
+| `pdf.paragraph(text, opts)` / `{ … }` | `<P>` |
+| `pdf.figure(alt_text:) { … }` | `<Figure>` with `/Alt` |
+
+Supported structure attributes: `:Alt`, `:ActualText`, `:Lang`, `:Scope`.
+
+## Compatibility
+
+Semantic-versioned. The `~>` dependency bounds are the compatibility contract:
+
+| prawn-accessibility | prawn | pdf-core | prawn-table (optional) |
+|---|---|---|---|
+| 1.x | `~> 2.5` | `~> 0.10` | `~> 0.2` |
+
+Tested on Ruby 3.1–3.4.
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec      # specs, including a regression suite proving untagged
+                       # output is unaffected
+bundle exec rubocop
+```
+
+## License
+
+Tri-licensed under the same terms as Prawn: Matz's Ruby license (see
+[LICENSE](LICENSE)) or [GPLv2](GPLv2) or [GPLv3](GPLv3). See [COPYING](COPYING)
+for a summary.

data/lib/prawn/accessibility/document.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require 'prawn'
+require_relative 'pdf_core'
+
+module Prawn
+  module Accessibility
+    # Instance methods mixed into {Prawn::Document} to provide the high-level
+    # tagged-PDF (accessibility) API. When a document is created with
+    # <tt>marked: true</tt>, content can be wrapped in structure elements that
+    # screen readers and assistive technologies use to navigate the document.
+    #
+    # @example
+    #   pdf = Prawn::Document.new(marked: true, language: 'en-US')
+    #
+    #   pdf.structure(:H1) do
+    #     pdf.text 'Document Title'
+    #   end
+    #
+    #   pdf.structure(:P) do
+    #     pdf.text 'Body paragraph text.'
+    #   end
+    #
+    #   pdf.artifact do
+    #     pdf.text 'Page 1'  # not read by screen readers
+    #   end
+    module DocumentExtensions
+      # Whether this document is tagged for accessibility.
+      #
+      # @return [Boolean]
+      def tagged?
+        renderer.marked?
+      end
+
+      # Wrap content in a structure element. The block's content will be
+      # associated with the given tag in the document's structure tree.
+      #
+      # Can be nested — inner structure calls become children of the outer.
+      #
+      # @param tag [Symbol] PDF structure type (:Document, :Part, :Sect,
+      #   :H1-:H6, :P, :L, :LI, :Lbl, :LBody, :Table, :TR, :TH, :TD,
+      #   :Figure, :Formula, :Form, :Span, :Link, :Note, :BlockQuote,
+      #   :Caption, :TOC, :TOCI, :Reference)
+      # @param attributes [Hash] optional attributes
+      # @option attributes [String] :Alt alternative text (for Figure, Formula)
+      # @option attributes [String] :ActualText replacement text for screen
+      #   readers (e.g., "required" for "*", "selected" for "X")
+      # @option attributes [String] :Lang language override for this element
+      # @option attributes [Symbol] :Scope table header scope (:Column, :Row, :Both)
+      # @yield content to render inside this structure element
+      # @return [void]
+      def structure(tag, attributes = {}, &block)
+        return yield if !tagged? || !block
+
+        tree = renderer.structure_tree
+        tree.begin_element(tag, attributes)
+        tree.mark_content(tag, &block)
+        tree.end_element
+      end
+
+      # Wrap content in a structure element without marking the content
+      # directly. Use this for container elements (Table, TR, L, LI) where
+      # the children will each have their own marked content.
+      #
+      # @param tag [Symbol] PDF structure type
+      # @param attributes [Hash] optional attributes
+      # @yield content to render inside this structure element
+      # @return [void]
+      def structure_container(tag, attributes = {}, &block)
+        return yield if !tagged? || !block
+
+        tree = renderer.structure_tree
+        tree.begin_element(tag, attributes)
+        yield
+        tree.end_element
+      end
+
+      # Mark content as an artifact (decorative, not read by screen readers).
+      # Use for page numbers, decorative borders, backgrounds, watermarks.
+      #
+      # @param type [Symbol, nil] artifact type (:Pagination, :Layout,
+      #   :Page, :Background)
+      # @yield content to render as artifact
+      # @return [void]
+      def artifact(type: nil, &block)
+        return yield if !tagged? || !block
+
+        renderer.structure_tree.mark_artifact(artifact_type: type, &block)
+      end
+
+      # Render a heading at the specified level.
+      #
+      # @param level [Integer] heading level 1-6
+      # @param content [String] heading text
+      # @param options [Hash] options passed to `text()`
+      # @return [void]
+      def heading(level, content, options = {})
+        tag = :"H#{level}"
+        if tagged?
+          structure(tag) { text(content, options) }
+        else
+          text(content, options)
+        end
+      end
+
+      # Render text wrapped in a paragraph structure element.
+      #
+      # @param content [String, nil] text to render. If nil, yields a block.
+      # @param options [Hash] options passed to `text()`
+      # @yield optional block for complex paragraph content
+      # @return [void]
+      def paragraph(content = nil, options = {}, &block)
+        if tagged?
+          if block
+            structure(:P, &block)
+          else
+            structure(:P) { text(content, options) }
+          end
+        elsif block
+          yield
+        else
+          text(content, options)
+        end
+      end
+
+      # Render an image wrapped in a Figure structure element with alt text.
+      #
+      # @param alt_text [String] alternative text for the image
+      # @yield block that calls `image()` or other drawing methods
+      # @return [void]
+      def figure(alt_text:, &block)
+        if tagged?
+          structure(:Figure, Alt: alt_text, &block)
+        else
+          yield
+        end
+      end
+    end
+  end
+end
+
+# --- Patches applied to Prawn::Document -------------------------------------
+
+# Accept the accessibility options in Prawn::Document.new. VALID_OPTIONS is a
+# frozen constant; redefine it (remove + set avoids the redefinition warning).
+original_valid_options = Prawn::Document::VALID_OPTIONS
+Prawn::Document.send(:remove_const, :VALID_OPTIONS)
+Prawn::Document.const_set(
+  :VALID_OPTIONS,
+  (original_valid_options + %i[marked language]).freeze,
+)
+
+Prawn::Document.include(Prawn::Accessibility::DocumentExtensions)

data/lib/prawn/accessibility/marked_content.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module PDF
+  module Core
+    # Provides methods for emitting marked content operators (BMC/BDC/EMC)
+    # in PDF content streams. These operators associate content with structure
+    # elements for accessibility (tagged PDF).
+    #
+    # @api private
+    module MarkedContent
+      # Begin a marked content sequence with no properties.
+      #
+      # @param tag [Symbol] structure type tag (e.g., :P, :Span, :Artifact)
+      # @return [void]
+      def begin_marked_content(tag)
+        add_content("/#{tag} BMC")
+      end
+
+      # Begin a marked content sequence with properties (BDC operator).
+      #
+      # @param tag [Symbol] structure type tag
+      # @param properties [Hash] properties dict (typically includes :MCID)
+      # @return [void]
+      def begin_marked_content_with_properties(tag, properties = {})
+        props = PDF::Core.pdf_object(properties, true)
+        add_content("/#{tag} #{props} BDC")
+      end
+
+      # End a marked content sequence.
+      #
+      # @return [void]
+      def end_marked_content
+        add_content('EMC')
+      end
+
+      # Wrap a block in a marked content sequence (BMC/EMC).
+      #
+      # @param tag [Symbol] structure type tag
+      # @yield content to wrap
+      # @return [void]
+      def marked_content_sequence(tag)
+        begin_marked_content(tag)
+        yield if block_given?
+        end_marked_content
+      end
+
+      # Wrap a block in a marked content sequence with properties (BDC/EMC).
+      #
+      # @param tag [Symbol] structure type tag
+      # @param properties [Hash] properties dict
+      # @yield content to wrap
+      # @return [void]
+      def marked_content_sequence_with_properties(tag, properties = {})
+        begin_marked_content_with_properties(tag, properties)
+        yield if block_given?
+        end_marked_content
+      end
+    end
+  end
+end

data/lib/prawn/accessibility/pdf_core.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require 'pdf/core'
+require_relative 'marked_content'
+require_relative 'structure_tree'
+
+module Prawn
+  module Accessibility
+    # Patches applied to the published +pdf-core+ gem to add tagged-PDF
+    # support. All patches are additive or +prepend+-based: the original
+    # (untagged) behavior is preserved and only diverges when a document is
+    # created with <tt>marked: true</tt>.
+    #
+    # @api private
+    module PDFCore
+      # Prepended onto {PDF::Core::DocumentState#initialize}. Threads the
+      # +:marked+ and +:language+ options through to the object store's
+      # catalog after the original initializer has built the store.
+      #
+      # @api private
+      module DocumentStatePatch
+        def initialize(options)
+          super
+
+          @store.root.data[:MarkInfo] = { Marked: true } if options[:marked]
+          @store.root.data[:Lang] = options[:language] if options[:language]
+        end
+      end
+
+      # Prepended onto {PDF::Core::Renderer#initialize}. When the document is
+      # marked, wires up a {PDF::Core::StructureTree}, schedules its
+      # finalization before render, and bumps the PDF version to 1.7.
+      #
+      # @api private
+      module RendererPatch
+        def initialize(state)
+          super
+
+          return unless state.store.marked?
+
+          @structure_tree = PDF::Core::StructureTree.new(self)
+          before_render { |_doc_state| @structure_tree.finalize! }
+          min_version(1.7)
+        end
+
+        # The structure tree for this document, or nil if not tagged.
+        #
+        # @return [PDF::Core::StructureTree, nil]
+        attr_reader :structure_tree
+
+        # Whether this document is marked (tagged for accessibility).
+        #
+        # @return [Boolean]
+        def marked?
+          state.store.marked?
+        end
+      end
+    end
+  end
+end
+
+# --- Additive re-opens ------------------------------------------------------
+
+module PDF
+  module Core
+    class ObjectStore
+      # Whether this document is marked (tagged for accessibility).
+      #
+      # @return [Boolean]
+      def marked?
+        root.data.key?(:MarkInfo) && root.data[:MarkInfo][:Marked] == true
+      end
+    end
+  end
+end
+
+PDF::Core::Renderer.include(PDF::Core::MarkedContent)
+PDF::Core::DocumentState.prepend(Prawn::Accessibility::PDFCore::DocumentStatePatch)
+PDF::Core::Renderer.prepend(Prawn::Accessibility::PDFCore::RendererPatch)