prawn-accessibility 1.0.0 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 455b571866fccd0796f13c09d4996994e802d7acdb995c8ad190f0f7a4af0638
-  data.tar.gz: e6f77dd230dac3867dfaceb4ab5333f9b2bdaac67fd438d58281cc3fb6ee34b5
+  metadata.gz: 23e35addd032e68085d39678ec492b25122be0f739864f464cf26520da63ba58
+  data.tar.gz: 69de3798b80e4a16d8dcee828c18f29368e95afab0fb1706e3bae9d9ae5c9754
 SHA512:
-  metadata.gz: aaf6ec947a42cc40e683192f7d7f53a0ad17097d9078338e2fde56e9037d6a560032994860dd83f1395c3b0a9efc0e45b945f7cd3ba47a501a5992d3878fe4ab
-  data.tar.gz: 4e485adc403ff74434fd96efa854f8457892cd38788afe15c7883c36b00703cafbb14aab9d132c7985f1b0c01d79859be20565ee2a0e9d0747ef8efa774622f8
+  metadata.gz: 9229dd71238f4bd062aa89b09e5fa6f7747b4bd517932fff773b89270f89d7148c2232de4e89a6d0c399c8cb8357031183c83f701af4f0b728a66d196def3dae
+  data.tar.gz: b7671f5e4bb5d111a23715b8687066f83b8b85582e93336c9d63cb475c1619170475029f6964ec18bc4920e3b4220b34a4a4051390be5985616929c2310f3add

data/CHANGELOG.md

@@ -3,6 +3,26 @@
 All notable changes to this project are documented here. This project adheres
 to [Semantic Versioning](https://semver.org).
 
+## [1.1.1] - 2026-07-06
+
+- Simplify the gem description. Metadata only — no code changes.
+
+## [1.1.0] - 2026-07-05
+
+- **Opt in with `tagged: true`.** Documents are tagged only when created with
+  `Prawn::Document.new(tagged: true)`, matching the `tagged?` query and standard
+  "tagged PDF" terminology. The `marked:` option is removed (no alias).
+- Reduced the patching surface: **no `pdf-core` patches**. `MarkedContent` and
+  `StructureTree` now live under `Prawn::Accessibility` and use only the public
+  renderer API; the structure tree is owned by the document and finalized via
+  the existing `before_render` hook. The high-level API is mixed into
+  `Prawn::Document` with `include`.
+- Untagged output is unchanged (byte-for-byte stock Prawn). Header cells are
+  flagged at construction, so `Cell#header?` is consistent before and after draw.
+- Removed the low-level `@api private` symbols `renderer.marked?`,
+  `renderer.structure_tree`, `PDF::Core::MarkedContent`,
+  `PDF::Core::StructureTree`, and `PDF::Core::ObjectStore#marked?`.
+
 ## [1.0.0] - 2026-07-05
 
 Initial release.
@@ -21,7 +41,6 @@ Initial release.
   with header detection and `/Scope`. Activated automatically when
   `prawn-table` is present; not a required dependency.
 
-Repackaged from the stalled upstream PRs prawnpdf/pdf-core#67,
-prawnpdf/prawn#1391, and prawnpdf/prawn-table#164.
-
+[1.1.1]: https://github.com/mes-amis/prawn-accessibility/releases/tag/v1.1.1
+[1.1.0]: https://github.com/mes-amis/prawn-accessibility/releases/tag/v1.1.0
 [1.0.0]: https://github.com/mes-amis/prawn-accessibility/releases/tag/v1.0.0

data/README.md

@@ -9,9 +9,12 @@ 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.
+`prawn-table` gems — it does **not** fork them. The document API is mixed into
+`Prawn::Document`; only a couple of small method wrappers remain (and none in
+`pdf-core`).
+
+Tagging is opt-in: create a document with `tagged: true`. Without it, output is
+byte-for-byte identical to stock Prawn.
 
 ## Installation
 
@@ -33,7 +36,8 @@ gem 'prawn-table' # optional; enables <Table>/<TR>/<TH>/<TD> tagging
 ```ruby
 require 'prawn-accessibility'
 
-pdf = Prawn::Document.new(marked: true, language: 'en-US')
+# Opt in with tagged: true; set language: for the document's /Lang.
+pdf = Prawn::Document.new(tagged: true, language: 'en-US')
 
 pdf.heading(1, 'Annual Report')                                   # <H1>
 pdf.paragraph('Body text that a screen reader will read aloud.')  # <P>
@@ -43,12 +47,14 @@ pdf.figure(alt_text: 'Company logo') { pdf.image('logo.png') }    # <Figure> wit
 
 pdf.artifact(type: :Pagination) { pdf.text('Page 1') }            # decorative, not read
 
-# Tables auto-tag when the document is tagged:
+# Tables auto-tag while the document is tagged:
 pdf.table([['Name', 'Age'], ['Alice', '30']], header: true)       # <Table>/<TR>/<TH>/<TD>
 
 pdf.render_file('report.pdf')
 ```
 
+A document created without `tagged: true` renders a plain, untagged PDF.
+
 ### API
 
 | Method | Emits |

data/lib/prawn/accessibility/document.rb

@@ -1,35 +1,36 @@
 # frozen_string_literal: true
 
 require 'prawn'
-require_relative 'pdf_core'
+require_relative 'structure_tree'
 
 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.
+    # Instance methods included into {Prawn::Document} to provide the
+    # high-level tagged-PDF (accessibility) API.
     #
-    # @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
+    # Tagging is opt-in: create the document with <tt>tagged: true</tt> (see the
+    # initializer shim at the bottom of this file). Everything here is built on
+    # Prawn/pdf-core's *public* API (`renderer`, `state`, `min_version`,
+    # `before_render`); no core class is patched to support it.
     #
-    #   pdf.artifact do
-    #     pdf.text 'Page 1'  # not read by screen readers
-    #   end
+    # @example
+    #   pdf = Prawn::Document.new(tagged: true, language: 'en-US')
+    #   pdf.structure(:H1) { pdf.text 'Document Title' }
+    #   pdf.structure(:P)  { pdf.text 'Body paragraph text.' }
+    #   pdf.artifact       { pdf.text 'Page 1' } # not read by screen readers
     module DocumentExtensions
+      # The structure tree for this document, or nil if not tagged.
+      #
+      # @return [Prawn::Accessibility::StructureTree, nil]
+      def structure_tree
+        @accessibility_structure_tree
+      end
+
       # Whether this document is tagged for accessibility.
       #
       # @return [Boolean]
       def tagged?
-        renderer.marked?
+        !@accessibility_structure_tree.nil?
       end
 
       # Wrap content in a structure element. The block's content will be
@@ -52,7 +53,7 @@ module Prawn
       def structure(tag, attributes = {}, &block)
         return yield if !tagged? || !block
 
-        tree = renderer.structure_tree
+        tree = structure_tree
         tree.begin_element(tag, attributes)
         tree.mark_content(tag, &block)
         tree.end_element
@@ -69,7 +70,7 @@ module Prawn
       def structure_container(tag, attributes = {}, &block)
         return yield if !tagged? || !block
 
-        tree = renderer.structure_tree
+        tree = structure_tree
         tree.begin_element(tag, attributes)
         yield
         tree.end_element
@@ -85,7 +86,7 @@ module Prawn
       def artifact(type: nil, &block)
         return yield if !tagged? || !block
 
-        renderer.structure_tree.mark_artifact(artifact_type: type, &block)
+        structure_tree.mark_artifact(artifact_type: type, &block)
       end
 
       # Render a heading at the specified level.
@@ -136,18 +137,56 @@ module Prawn
         end
       end
     end
-  end
-end
 
-# --- Patches applied to Prawn::Document -------------------------------------
+    # Prepended onto {Prawn::Document#initialize} to support the
+    # <tt>Prawn::Document.new(tagged: true, language: 'en-US')</tt> API.
+    # Tagging is opt-in: a document is tagged only when <tt>tagged: true</tt> is
+    # passed.
+    #
+    # It strips the accessibility options before delegating to the original
+    # initializer (so no change to +VALID_OPTIONS+ is needed), then wires up
+    # tagging and runs the user block — in that order, so the block runs with
+    # tagging already active.
+    #
+    # @api private
+    module OptionInitializer
+      def initialize(options = {}, &block)
+        opts = options.dup
+        tagged = opts.delete(:tagged)
+        language = opts.delete(:language)
+
+        # Delegate to the original initializer WITHOUT the block, so we can run
+        # it ourselves after tagging is wired up.
+        super(opts)
 
-# 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,
-)
+        install_accessibility(language) if tagged
+
+        return unless block
+
+        block.arity < 1 ? instance_eval(&block) : block[self]
+      end
+
+      private
+
+      # Set up tagged-PDF output: mark the catalog, create the structure tree,
+      # bump the PDF version to 1.7, and finalize the tree at render time via
+      # the renderer's public `before_render` hook.
+      #
+      # @param language [String, nil] optional document language (BCP 47 tag)
+      # @return [void]
+      def install_accessibility(language)
+        catalog = state.store.root.data
+        catalog[:MarkInfo] = { Marked: true }
+        catalog[:Lang] = language if language
+
+        @accessibility_structure_tree = Prawn::Accessibility::StructureTree.new(renderer)
+        renderer.min_version(1.7)
+        tree = @accessibility_structure_tree
+        renderer.before_render { |_state| tree.finalize! }
+      end
+    end
+  end
+end
 
 Prawn::Document.include(Prawn::Accessibility::DocumentExtensions)
+Prawn::Document.prepend(Prawn::Accessibility::OptionInitializer)

data/lib/prawn/accessibility/marked_content.rb

@@ -1,10 +1,15 @@
 # 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).
+module Prawn
+  module Accessibility
+    # Emits marked content operators (BMC/BDC/EMC) into a PDF content stream.
+    # These operators associate content with structure elements for
+    # accessibility (tagged PDF).
+    #
+    # This is a mixin: the including object must respond to `add_content(str)`
+    # (as {PDF::Core::Renderer} does). It therefore needs no changes to any
+    # pdf-core class — {StructureTree} includes it and forwards `add_content`
+    # to the renderer.
     #
     # @api private
     module MarkedContent

data/lib/prawn/accessibility/structure_tree.rb

@@ -1,17 +1,25 @@
 # frozen_string_literal: true
 
-module PDF
-  module Core
+require_relative 'marked_content'
+
+module Prawn
+  module Accessibility
     # 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.).
     #
+    # It talks to the document exclusively through the *public* renderer API
+    # (`ref!`, `deref`, `add_content`, `state`), so it requires no patches to
+    # any pdf-core class.
+    #
     # PDF spec references: Section 14.7 (Logical Structure)
     #
     # @api private
     class StructureTree
+      include MarkedContent
+
       # @return [PDF::Core::Renderer] owning renderer
       attr_reader :renderer
 
@@ -148,10 +156,10 @@ module PDF
         # 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 })
+        # Emit BDC/EMC in content stream (via the MarkedContent mixin)
+        begin_marked_content_with_properties(tag, { MCID: mcid })
         yield if block_given?
-        renderer.end_marked_content
+        end_marked_content
       end
 
       # Mark content as an artifact (decorative, not read by screen readers).
@@ -162,14 +170,12 @@ module PDF
       # @return [void]
       def mark_artifact(artifact_type: nil)
         if artifact_type
-          renderer.begin_marked_content_with_properties(
-            :Artifact, { Type: artifact_type },
-          )
+          begin_marked_content_with_properties(:Artifact, { Type: artifact_type })
         else
-          renderer.begin_marked_content(:Artifact)
+          begin_marked_content(:Artifact)
         end
         yield if block_given?
-        renderer.end_marked_content
+        end_marked_content
       end
 
       # Finalize the structure tree before rendering. Called via
@@ -190,6 +196,15 @@ module PDF
 
       private
 
+      # Forward content emission (used by the MarkedContent mixin) to the
+      # renderer's public API.
+      #
+      # @param str [String]
+      # @return [void]
+      def add_content(str)
+        renderer.add_content(str)
+      end
+
       # The current open structure element, or nil if none.
       #
       # @return [PDF::Core::Reference, nil]

data/lib/prawn/accessibility/table.rb

@@ -3,6 +3,17 @@
 # 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.
+#
+# prawn-table hard-instantiates Prawn::Table and offers no hook around cell
+# drawing, so these three `prepend`s are the irreducible patching until upstream
+# grows render hooks:
+#
+#   1. Prawn::Table#initialize      — flag header cells (at construction)
+#   2. Prawn::Table#draw            — wrap the whole table in <Table>
+#   3. Prawn::Table::Cell.draw_cells — wrap each row/cell in <TR>/<TH>/<TD>
+#
+# #draw and .draw_cells delegate to `super` in the untagged path, so untagged
+# tables are unchanged. Everything else here is additive (new methods only).
 
 unless defined?(Prawn::Table)
   raise 'prawn/accessibility/table requires prawn-table to be loaded first'
@@ -12,12 +23,14 @@ 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+).
+    # is tagged.
     #
     # @api private
     module TablePatch
-      # Prepended onto {Prawn::Table#initialize} to flag header cells after
-      # the table has been built and positioned.
+      # Prepended onto {Prawn::Table}. Flags header cells at construction (so
+      # +Cell#header?+ is consistent whether or not the table has been drawn),
+      # and wraps drawing in a +<Table>+ structure element when the document is
+      # tagged.
       #
       # @api private
       module TableInstancePatch
@@ -26,8 +39,6 @@ module Prawn
           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() }

data/lib/prawn/accessibility/version.rb

@@ -3,6 +3,6 @@
 module Prawn
   module Accessibility
     # Gem version. Follows Semantic Versioning (https://semver.org).
-    VERSION = '1.0.0'
+    VERSION = '1.1.1'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: prawn-accessibility
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.1
 platform: ruby
 authors:
 - Mes Amis
@@ -42,11 +42,6 @@ description: |
   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: []
@@ -63,7 +58,6 @@ files:
 - 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

data/lib/prawn/accessibility/pdf_core.rb

@@ -1,79 +0,0 @@
-# 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)