stationery 0.12.0 → 0.12.2

data/lib/stationery/elements/forms.rb

@@ -9,7 +9,9 @@ module Stationery
   module Elements
     # A text input. `width:` is :full or points; `multiline:`, `max_length:`,
     # `comb:` (a cell count, or true with max_length:), `read_only:`,
-    # `required:`, `font_size:`, `border:`, `background:` and `radius:`.
+    # `required:`, `font_size:` (points, or :auto with `min_font_size:` and
+    # `max_font_size:`), `align:` (:left, :center, :right), `color:`,
+    # `border:`, `background:` and `radius:`.
     def text_field(name, value: "", width: :full, height: 22, at: nil, **)
       field_node(Forms::Field.new(:text, name, value: value.to_s, typeface: field_typeface, **), width:, height:, at:)
     end
@@ -28,7 +30,7 @@ module Stationery
     end
 
     # A drop-down (combo box) of `options`; `editable: true` also accepts
-    # typed values.
+    # typed values. `font_size:`, `align:` and `color:` as a text field's.
     def select(name, options:, value: nil, width: :full, height: 22, at: nil, **)
       field = Forms::Field.new(:select, name, value: value&.to_s, options: options.map(&:to_s),
                                               typeface: field_typeface, **)

data/lib/stationery/forms/acro_form.rb

@@ -93,7 +93,7 @@ module Stationery
       # known to exist; nil without a signature.
       def signed
         return unless @signature
-        return @writer.add(@signature.dictionary) if @widgets.any? { |widget| signs?(widget) }
+        return @writer.add_unpacked(@signature.dictionary) if @widgets.any? { |widget| signs?(widget) }
 
         raise ArgumentError, %(sign field: names "#{@signature.field}", but the document has no such signature_field)
       end

data/lib/stationery/forms/appearance.rb

@@ -16,14 +16,21 @@ module Stationery
       # The check mark's corners in the unit square (y down) and its stroke.
       CHECK = { points: [[0.22, 0.52], [0.42, 0.72], [0.78, 0.28]], stroke: 0.12 }.freeze
       DOT = 0.45
+      # What /DA and the appearance say when the value is black.
+      BLACK = "0 g"
       SIGNATURE = { rule: 14, label_size: 7, label_baseline: 4, label_gray: 0.42 }.freeze
 
+      # The size the value is drawn at: the field's, or what `font_size:
+      # :auto` fits (see AutoSize).
+      attr_reader :size
+
       # `resources` are the render's, where the field's fonts get their names.
       def initialize(field, width, height, resources = nil)
         @field = field
         @width = width
         @height = height
         @type = field.typeface.with(resources)
+        @size = field.auto_size? ? AutoSize.new(field, @type, width, height).size : field.font_size
         @contents = contents
         keep
       end
@@ -34,14 +41,18 @@ module Stationery
       # The resource names of the fonts it draws with or keeps for editing.
       def font_names = @type.names
 
-      # What the field's /DA says: the font and size a viewer redraws the
-      # value with. nil for a field without variable text.
+      # What the field's /DA says: the font, size (0 for auto) and colour a
+      # viewer redraws the value with. nil for a field without variable text.
       def default_appearance
         return unless @field.variable_text?
 
-        "/#{@type.name} #{num(@field.font_size)} Tf 0 g"
+        "/#{@type.name} #{@field.auto_size? ? 0 : num(size)} Tf #{text_color}"
       end
 
+      # What it paints: its content streams and its /DA, for a check of the
+      # colours they use (see PDF::Conformance).
+      def paints = [*(@contents.is_a?(Hash) ? @contents.values : @contents), default_appearance].compact
+
       # One stream, or a Hash of streams by appearance state for buttons.
       # `fonts` are the references by resource name.
       def streams(fonts)
@@ -54,7 +65,7 @@ module Stationery
       private
 
       def options = @field.options
-      def size = @field.font_size
+      def text_color = @field.color == Field::BLACK ? BLACK : @field.color.fill
       def num(value) = PDF::Serializer.number(value.is_a?(Float) && value == value.round ? value.round : value)
 
       def contents
@@ -98,29 +109,23 @@ module Stationery
         return comb_cells if options[:comb]
         return multiline_runs if options[:multiline]
 
-        [[PADDING, middle_baseline, @field.value.to_s]]
+        value = @field.value.to_s
+        [[start(value), middle_baseline, value]]
       end
 
       def multiline_runs
         top = @height - PADDING - @type.ascent(size)
-        wrap(@field.value.to_s, @width - (2 * PADDING)).each_with_index.map do |line, index|
-          [PADDING, top - (index * size * LEADING), line]
+        AutoSize.wrap(@type, @field.value.to_s, @width - (2 * PADDING), size).each_with_index.map do |line, index|
+          [start(line), top - (index * size * LEADING), line]
         end
       end
 
-      # The value broken into lines no wider than `width`, keeping its own
-      # line breaks; a word wider than a line stands alone.
-      def wrap(text, width)
-        text.split("\n", -1).flat_map do |paragraph|
-          paragraph.split.each_with_object([+""]) do |word, lines|
-            candidate = lines.last.empty? ? word : "#{lines.last} #{word}"
-            if lines.last.empty? || @type.width(candidate, size) <= width
-              lines[-1] = candidate
-            else
-              lines << word
-            end
-          end
-        end
+      # Where a line starts: aligned within the box less its padding, as a
+      # viewer does (PDF 32000-1, 12.7.3.3).
+      def start(line)
+        return PADDING if @field.align == :left
+
+        PADDING + Geometry.align_offset(@field.align, @width - (2 * PADDING), @type.width(line, size))
       end
 
       def comb_cells
@@ -131,7 +136,7 @@ module Stationery
       end
 
       def variable_text(runs)
-        ops = ["/Tx BMC", "q", "1 1 #{num(@width - 2)} #{num(@height - 2)} re W n", "0 g"]
+        ops = ["/Tx BMC", "q", "1 1 #{num(@width - 2)} #{num(@height - 2)} re W n", text_color]
         runs.reject { |_, _, text| text.empty? }.each do |x, y, text|
           ops.push("BT", "#{num(x)} #{num(y)} Td", *@type.show(text, size), "ET")
         end

data/lib/stationery/forms/auto_size.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Forms
+    # The size `font_size: :auto` draws a field's value at: the largest that
+    # fits the field's box less its padding, no larger than `max_font_size:`
+    # and no smaller than `min_font_size:` (4 points by default, the smallest
+    # Chrome's PDFium auto-sizes to). Sizes are whole tenths of a point,
+    # rounded down.
+    #
+    # A typeface's widths and heights are linear in the size, so one line and
+    # a comb field's cells are arithmetic; wrapped lines are not, and their
+    # size is found by bisection. Only the typeface's measures are asked:
+    # nothing is drawn or named here.
+    class AutoSize
+      MIN = 4
+      # Measures are taken at this size and scaled: less rounding than at 1.
+      UNIT = 100.0
+
+      # The value broken into lines no wider than `width` at `size`, keeping
+      # its own line breaks; a word wider than a line stands alone.
+      def self.wrap(type, text, width, size)
+        text.split("\n", -1).flat_map do |paragraph|
+          paragraph.split.each_with_object([+""]) do |word, lines|
+            candidate = lines.last.empty? ? word : "#{lines.last} #{word}"
+            if lines.last.empty? || type.width(candidate, size) <= width
+              lines[-1] = candidate
+            else
+              lines << word
+            end
+          end
+        end
+      end
+
+      # `type` is the typeface the appearance draws with; `width` and
+      # `height` the widget's.
+      def initialize(field, type, width, height)
+        @field = field
+        @type = type
+        @inner_width = width - (2 * Appearance::PADDING)
+        @inner_height = height - (2 * Appearance::PADDING)
+        @cell = field.options[:comb] && width.fdiv(field.max_length)
+      end
+
+      def size
+        min = @field.min_font_size || [MIN, @field.max_font_size].compact.min
+        max = [tenth([@field.max_font_size, height_fit].compact.min), min].max
+        fit = @field.options[:multiline] && !@cell ? lines_fit(min, max) : [max, width_fit].compact.min
+        [tenth(fit), min].max
+      end
+
+      private
+
+      def value = @field.value.to_s
+      def tenth(size) = (size * 10).floor / 10.0
+      def per_point(measure) = measure / UNIT
+      def glyph_box = per_point(@type.ascent(UNIT) + @type.descent(UNIT))
+      def height_fit = @inner_height / glyph_box
+
+      # What the width allows one line, or the widest character a cell; nil
+      # when the value has no width.
+      def width_fit
+        return cell_fit if @cell
+
+        width = per_point(@type.width(value, UNIT))
+        @inner_width / width if width.positive?
+      end
+
+      def cell_fit
+        widest = value[0, @field.max_length].chars.map { |char| per_point(@type.width(char, UNIT)) }.max
+        @cell / widest if widest&.positive?
+      end
+
+      # The largest tenth in min..max at which the wrapped value fits.
+      def lines_fit(min, max)
+        low = (min * 10).ceil
+        high = (max * 10).floor
+        return min unless high >= low && fits?(low / 10.0)
+
+        while low < high
+          middle = (low + high + 1) / 2
+          fits?(middle / 10.0) ? low = middle : high = middle - 1
+        end
+        low / 10.0
+      end
+
+      def fits?(size)
+        lines = AutoSize.wrap(@type, value, @inner_width, size)
+        height = @type.ascent(size) + ((lines.size - 1) * size * Appearance::LEADING) + @type.descent(size)
+        height <= @inner_height && lines.all? { |line| @type.width(line, size) <= @inner_width }
+      end
+    end
+  end
+end

data/lib/stationery/forms/field.rb

@@ -16,13 +16,20 @@ module Stationery
                comb: 25 }.freeze
       DEFAULTS = { font_size: 10, read_only: false, required: false, border: "#9CA3AF", background: "#FFFFFF",
                    radius: 2, tooltip: nil }.freeze
+      # What a text field and a select take beyond the defaults: where the
+      # value sits, its colour, and the bounds of `font_size: :auto`.
+      BOUNDS = %i[min_font_size max_font_size].freeze
+      STYLE = [:align, :color, *BOUNDS].freeze
       OPTIONS = {
-        text: %i[multiline max_length comb], checkbox: [], radio: %i[checked], select: %i[options editable],
-        signature: %i[label]
+        text: [:multiline, :max_length, :comb, *STYLE], checkbox: [], radio: %i[checked],
+        select: [:options, :editable, *STYLE], signature: %i[label]
       }.freeze
       VARIABLE_TEXT = %i[text select].freeze
+      # The /Q (quadding) of each `align:` (PDF 32000-1, 12.7.3.3).
+      ALIGNMENTS = { left: 0, center: 1, right: 2 }.freeze
+      BLACK = Color.parse("#000000")
 
-      attr_reader :kind, :name, :value, :options, :typeface
+      attr_reader :kind, :name, :value, :options, :typeface, :color
 
       def initialize(kind, name, value: nil, typeface: Standard.new, **options)
         @kind = kind
@@ -33,12 +40,24 @@ module Stationery
         raise ArgumentError, "unknown #{kind} field option: #{unknown.join(", ")}" if unknown.any?
 
         @options = DEFAULTS.merge(options)
+        @color = Color.parse(@options.fetch(:color, BLACK))
         validate_comb
+        validate_style
+      end
+
+      # A copy with `changes` to its options.
+      def with(**changes)
+        self.class.new(@kind, @name, value: @value, typeface: @typeface, **@options, **changes)
       end
 
       def segments = @name.split(".")
       def type = TYPES.fetch(@kind)
       def font_size = @options[:font_size]
+      # Whether the value is drawn at the largest size that fits (`font_size: :auto`).
+      def auto_size? = font_size == :auto
+      def min_font_size = @options[:min_font_size]
+      def max_font_size = @options[:max_font_size]
+      def align = @options.fetch(:align, :left)
       # Whether a viewer redraws its text when the value changes.
       def variable_text? = VARIABLE_TEXT.include?(@kind)
       # The accessible name: `tooltip:`, a signature's label, else the name.
@@ -62,6 +81,7 @@ module Stationery
       def field_entries(value = field_value, default_appearance: nil)
         entries = { FT: type, TU: PDF::TextString.new(tooltip) }
         entries[:DA] = default_appearance if default_appearance
+        entries[:Q] = ALIGNMENTS.fetch(align) unless align == :left
         entries[:Ff] = flags if flags.positive?
         entries[:V] = value unless value.nil?
         entries[:MaxLen] = max_length if max_length
@@ -126,6 +146,28 @@ module Stationery
 
         raise ArgumentError, "a comb field needs max_length: (or comb: <cells>)"
       end
+
+      def validate_style
+        raise ArgumentError, "align: is :left, :center or :right, not #{align.inspect}" unless ALIGNMENTS.key?(align)
+
+        points(:font_size, " or :auto") unless auto_size?
+        BOUNDS.each do |key|
+          next unless @options.key?(key)
+          raise ArgumentError, "#{key}: needs font_size: :auto" unless auto_size?
+
+          points(key)
+        end
+        return unless min_font_size && max_font_size && min_font_size > max_font_size
+
+        raise ArgumentError, "min_font_size: #{min_font_size} is above max_font_size: #{max_font_size}"
+      end
+
+      def points(key, alternative = "")
+        value = @options[key]
+        return if value.is_a?(Numeric) && value.positive?
+
+        raise ArgumentError, "#{key}: is a number of points#{alternative}, not #{value.inspect}"
+      end
     end
   end
 end

data/lib/stationery/monochrome/painting.rb

@@ -47,6 +47,16 @@ module Stationery
         super
       end
 
+      # A field's value is text: its colour is reported, or snapped in /DA
+      # and the appearance alike. Its frame is drawn as it is.
+      def widget(field, x, y, w, h, tag: nil)
+        if field.variable_text?
+          color, = @monochrome.paint(field.color, :text, @page)
+          field = field.with(color:) unless color.equal?(field.color)
+        end
+        super
+      end
+
       # A gradient is reported by its stops; snapped, it is a black fill or nothing.
       def shade_path(path, shading, matrix:, even_odd: false, opacity: nil)
         return super unless shading.respond_to?(:stops)

data/lib/stationery/pdf/assembler.rb

@@ -17,13 +17,15 @@ module Stationery
       # finished file, so it cannot be streamed. `writer:` is the Writer that
       # already holds the bodies of pages sealed as they were painted; it
       # brings its own encryption and sink. `print:` are the hints of
-      # PrintHints for the catalog.
+      # PrintHints for the catalog. `object_streams:` (true) packs what is not
+      # a stream into object streams (see Writer).
       def initialize(pages:, resources:, info: {}, outline: [], encryption: nil, tagging: nil, lang: nil,
                      page_labels: nil, attachments: [], xmp: true, xmp_extensions: {}, xmp_schemas: [],
-                     conformance: nil, signature: nil, sink: nil, writer: nil, print: nil)
+                     conformance: nil, signature: nil, sink: nil, writer: nil, print: nil, object_streams: false)
         raise ArgumentError, "a signed document cannot be streamed: sign needs the whole file" if signature && sink
 
         @writer = writer
+        @object_streams = object_streams
         @print = print
         @sink = sink
         @xmp_schemas = xmp_schemas
@@ -44,7 +46,7 @@ module Stationery
 
       # The file as a String, or the number of bytes streamed to the sink.
       def render
-        writer = @writer || Writer.new(encryption: @encryption, sink: @sink)
+        writer = @writer || Writer.new(encryption: @encryption, sink: @sink, object_streams: @object_streams)
         tree = writer.reserve
         refs = @resources.build(writer)
         @form = Forms::AcroForm.new(writer, fonts: refs.fetch(:Font), signature: @signature,

data/lib/stationery/pdf/conformance.rb

@@ -27,6 +27,8 @@ module Stationery
       OUTPUT_CONDITION = "sRGB IEC61966-2.1"
       PRINT = 4
       CMYK_OPERATOR = /^(?:-?[\d.]+ ){4}[kK]$/
+      # The colour a field's /DA sets, after its font and size.
+      CMYK_DEFAULT_APPEARANCE = /Tf (?:-?[\d.]+ ){4}k\z/
       # What a character no font has does: :raise, or :replace to draw the
       # font's stand-in for it (see Fonts::Font#stand_in).
       MISSING_GLYPHS = %i[raise replace].freeze
@@ -174,7 +176,18 @@ module Stationery
         pages.each_with_index do |page, index|
           subjects << "CMYK colour on page #{index + 1}" if page.content.match?(CMYK_OPERATOR)
         end
-        subjects
+        subjects + cmyk_fields(pages)
+      end
+
+      # A field's appearance and /DA are not page content: each is read on its own.
+      def cmyk_fields(pages)
+        widgets = pages.flat_map(&:annotations).select { |annotation| annotation[:widget] && annotation[:appearance] }
+        widgets.select { |annotation| cmyk_paint?(annotation[:appearance].paints) }
+               .map { |annotation| %(CMYK colour in form field "#{annotation[:widget].name}") }.uniq
+      end
+
+      def cmyk_paint?(paints)
+        paints.any? { |paint| paint.match?(CMYK_OPERATOR) || paint.match?(CMYK_DEFAULT_APPEARANCE) }
       end
     end
   end

data/lib/stationery/pdf/object_streams.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Stationery
+  module PDF
+    # The two stream objects of a compressed file (ISO 32000-1, 7.5.7 and
+    # 7.5.8): an object stream holding objects that are not streams, and the
+    # cross-reference stream that replaces the table and the trailer.
+    module ObjectStreams
+      # Objects in one object stream: a few hundred deflate to a tenth of
+      # their size, and a reader inflates the whole stream to reach one.
+      CAPACITY = 200
+      # Bytes of an entry's type, offset or object stream number, and
+      # generation or index.
+      WIDTHS = [1, 4, 2].freeze
+      FREE = [0, 0, 0xFFFF].freeze
+
+      module_function
+
+      # The object stream of `batch`, [number, value] pairs, its values
+      # written without encryption: the stream is encrypted whole.
+      def pack(batch)
+        header = String.new(encoding: Encoding::BINARY)
+        body = String.new(encoding: Encoding::BINARY)
+        batch.each do |number, value|
+          header << "#{number} #{body.bytesize} "
+          body << Serializer.dump(value) << "\n"
+        end
+        Stream.new(header + body, { Type: :ObjStm, N: batch.size, First: header.bytesize })
+      end
+
+      # The cross-reference stream of `locations`, one per object from 1: an
+      # Integer offset in the file, or [object stream, index] for a packed
+      # object. `trailer` is what the trailer dictionary would hold.
+      def xref(locations, trailer)
+        fields = FREE.dup
+        locations.each { |at| at.is_a?(Integer) ? fields.push(1, at, 0) : fields.push(2, at[0], at[1]) }
+        Stream.new(fields.pack("CNn" * (fields.size / 3)), trailer.merge(Type: :XRef, W: WIDTHS))
+      end
+    end
+  end
+end

data/lib/stationery/pdf/writer.rb

@@ -5,7 +5,8 @@ require "digest/md5"
 module Stationery
   module PDF
     # Collects numbered objects and writes them as a PDF file with a classic
-    # cross-reference table. `render` returns the file as a String with the
+    # cross-reference table, or with `object_streams: true` packed into
+    # object streams with a cross-reference stream (see ObjectStreams). `render` returns the file as a String with the
     # objects in numbered order. With a `sink:` (anything answering
     # `call(bytes)`) the file goes there in pieces instead: `flush` writes every
     # object set so far and drops it, so objects leave in the order they were
@@ -16,8 +17,14 @@ module Stationery
 
       # `encryption` (an Encryption::StandardSecurity) encrypts every string
       # and stream except those of its own /Encrypt dictionary.
-      def initialize(encryption: nil, sink: nil)
+      #
+      # With `object_streams: true` every object that is not a stream goes
+      # into a deflated object stream, but for the Encrypt dictionary and an
+      # object added with #add_unpacked (a signature dictionary, which is
+      # filled in once the file is written and found by its bytes).
+      def initialize(encryption: nil, sink: nil, object_streams: false)
         @objects = []
+        @loose = [] if object_streams
         @offsets = []
         @encryption = encryption
         @sink = sink
@@ -45,6 +52,13 @@ module Stationery
         set(reserve, value)
       end
 
+      # Adds an object that stays out of the object streams.
+      def add_unpacked(value)
+        ref = add(value)
+        @loose << ref.id if @loose
+        ref
+      end
+
       # With a sink: writes every object set and not yet written, lowest number
       # first, and drops it. References to objects still unset stay valid, as
       # the cross-reference table is written last. Without a sink it does
@@ -66,9 +80,10 @@ module Stationery
         end
 
         write_pending
-        xref = @size
         id = HexString.new(file_id)
+        return write_xref_stream(root, info, id) if @loose
 
+        xref = @size
         emit("xref\n0 #{@objects.size + 1}\n0000000000 65535 f \n")
         @offsets.each { |offset| emit(format("%010d 00000 n \n", offset)) }
         emit("trailer\n#{Serializer.dump(trailer(root, info, id))}")
@@ -79,6 +94,8 @@ module Stationery
       private
 
       def write_pending
+        return pack_pending if @loose
+
         @objects.each_with_index do |object, index|
           next if object.nil? || object.equal?(WRITTEN)
 
@@ -87,14 +104,51 @@ module Stationery
         end
       end
 
+      # Streams, the Encrypt dictionary and what was added with #add_unpacked
+      # are written as they are, the rest into object streams of at most
+      # ObjectStreams::CAPACITY objects; the last one is closed with the flush.
+      def pack_pending
+        batch = []
+        @objects.each_with_index do |object, index|
+          next if object.nil? || object.equal?(WRITTEN)
+
+          number = index + 1
+          if object.is_a?(Stream) || @loose.include?(number) || number == @encrypt&.id
+            write_object(number, object)
+          else
+            batch << [number, object]
+            batch = write_object_stream(batch) if batch.size == ObjectStreams::CAPACITY
+          end
+          @objects[index] = WRITTEN
+        end
+        write_object_stream(batch) if batch.any?
+      end
+
+      def write_object_stream(batch)
+        @objects << WRITTEN
+        number = @objects.size
+        batch.each_with_index { |(packed, _), index| @offsets[packed - 1] = [number, index] }
+        write_object(number, ObjectStreams.pack(batch))
+        []
+      end
+
+      # The cross-reference stream, its own entry among them, never encrypted.
+      def write_xref_stream(root, info, id)
+        @objects << WRITTEN
+        number = @objects.size
+        xref = @offsets[number - 1] = @size
+        write_object(number, ObjectStreams.xref(@offsets, trailer(root, info, id)), nil)
+        emit("startxref\n#{xref}\n%%EOF\n")
+        @buffer || @size
+      end
+
       def trailer(root, info, id)
         trailer = { Size: @objects.size + 1, Root: root, Info: info, ID: [id, id] }
         @encrypt ? trailer.merge(Encrypt: @encrypt) : trailer
       end
 
-      def write_object(number, object)
+      def write_object(number, object, crypt = crypt_for(number))
         @offsets[number - 1] = @size
-        crypt = crypt_for(number)
         emit("#{number} 0 obj\n")
         if object.is_a?(Stream)
           data = crypt ? crypt.call(object.data) : object.data

data/lib/stationery/raster/render.rb

@@ -16,7 +16,7 @@ module Stationery
       # What only a PDF has: refused when asked for, left alone when the
       # class declares it.
       PDF_ONLY = %i[sign encrypt conformance attachments print tagged page_labels xmp factur_x incremental
-                    missing_glyphs].freeze
+                    missing_glyphs object_streams].freeze
       GREY = "\x01-\xFE".b
       DARK = "\x00-\x7F".b
       LIGHT = "\x80-\xFF".b

data/lib/stationery/skill/recipes/form.md.erb

@@ -23,17 +23,17 @@ class ApplicationFormPdf < Stationery::Document
     text "Membership application", size: 20, weight: :bold, heading: 1
     spacer 16
     row(gap: 12) do
-      labelled("Full name") { text_field "applicant.name", value: @name, required: true }
-      labelled("Email") { text_field "applicant.email" }
+      labelled("Full name") { text_field "applicant.name", value: @name, required: true, tooltip: "Full name" }
+      labelled("Email") { text_field "applicant.email", tooltip: "Email" }
     end
     spacer 10
     row(gap: 12) do
-      column(width: 90) { labelled_field("Postcode") { text_field "applicant.postcode", comb: 5 } }
-      labelled("Country") { select "applicant.country", options: %w[Sweden Norway Denmark], value: "Sweden" }
+      column(width: 90) { labelled_field("Postcode") { text_field "applicant.postcode", comb: 5, tooltip: "Postcode" } }
+      labelled("Country") { select "applicant.country", options: %w[Sweden Norway Denmark], value: "Sweden", tooltip: "Country" }
     end
     spacer 10
     labelled_field("Plan") do
-      radio "plan", "basic", label: "Basic"
+      radio "plan", "basic", label: "Basic", tooltip: "Plan"         # a radio group is named by its first choice
       radio "plan", "pro", label: "Pro", checked: true
     end
     spacer 10
@@ -72,7 +72,10 @@ end
   which paints the appearances the gem writes: `mutool draw -r 96 -o form-%d.png form.pdf`
   (`pdftoppm` draws the values but not the borders). `stationery inspect form.pdf` lists each
   field with its rectangle and value.
-- Fields keep PDF/A and PDF/UA (every field has an accessible name from `tooltip:` or its label).
+- Fields keep PDF/A and PDF/UA. Every field has an accessible name: its `tooltip:`, else a check
+  box's or signature field's `label:`, else its field name (`applicant.name`), which is what a
+  screen reader then says. So a text field, a select and a radio group get a `tooltip:`, as above:
+  the text printed beside a field is not its name.
 - Signing the file: `sign certificate:, key:, field: "signature"` fills the signature field with
   a digital signature (see [../reference/conformance.md](../reference/conformance.md)).
 - Every option of every field: [../reference/forms.md](../reference/forms.md) and <%= docs("forms") %>.

data/lib/stationery/skill/recipes/invoice.md.erb

@@ -93,9 +93,9 @@ class InvoicePdf < Stationery::Document
 
   def subtotal = @lines.sum { |line| line.quantity * line.unit_cents }
 
-  def vat_by_rate
-    @lines.group_by(&:vat_rate).transform_values do |lines|
-      (lines.sum { |line| line.quantity * line.unit_cents } * lines.first.vat_rate / 100.0).round
+  def vat_by_rate                                      # exact: Rational, rounded once per rate
+    @lines.group_by(&:vat_rate).to_h do |rate, lines|
+      [rate, (lines.sum { |line| line.quantity * line.unit_cents } * Rational(rate, 100)).round]
     end
   end
 
@@ -108,9 +108,12 @@ end
 
 ## What matters here
 
-- **Money is computed by the application**, in integer cents or `BigDecimal`, never in Floats;
-  the document only formats it. Totals are ordinary table rows: a cell `{ content:, colspan: }`
-  spans columns, `t.rows(-3..)` selects the last three rows.
+- **Money is integer cents** (or `BigDecimal`), never a Float. This document derives the line
+  amounts and VAT from its lines, exactly (`Rational(rate, 100)`, rounded once per rate); an
+  application whose invoice already holds its totals, as its books have them, passes those in
+  and the document only formats them, so the PDF cannot disagree with the ledger by a cent.
+  Totals are ordinary table rows: a cell `{ content:, colspan: }` spans columns, `t.rows(-3..)`
+  selects the last three rows.
 - **A table has black 0.5 pt borders on every cell by default.** `cell: { borders: [] }` takes
   them away; `borders: [:top]` on a selection draws one rule. `header: true` repeats the first row
   on every page the table continues onto; `t.zebra(from:, to:, color:)` stripes rows.
@@ -118,9 +121,10 @@ end
   as wide as the page.
 - **PDF/A-3b** (`conformance :pdf_a3b`) embeds the sRGB output intent and XMP identification, and
   raises `Stationery::ConformanceError` instead of writing a file that breaks the claim: a CMYK
-  colour, `encrypt`, or a character no font has (unless `missing_glyphs: :replace`, as above). Set
-  `metadata title:`. Transparency (a PNG logo with alpha) is allowed. Validate the file with
-  veraPDF: `verapdf --format text -v --flavour 3b invoice_pdf.pdf` prints `PASS` (`brew install
+  colour, or a character no font has (unless `missing_glyphs: :replace`, as above). `encrypt` with
+  a conformance level raises `ArgumentError` before anything renders: the two contradict each
+  other. Set `metadata title:`. Transparency (a PNG logo with alpha) is allowed. Validate the
+  file with veraPDF: `verapdf --format text -v --flavour 3b invoice_pdf.pdf` prints `PASS` (`brew install
   verapdf`; with Docker, see [../reference/conformance.md](../reference/conformance.md)).
 - An application that would rather send a plain PDF than none rescues the claim:
 

data/lib/stationery/skill/recipes/label.md.erb

@@ -73,7 +73,8 @@ every change:
    `CODE-128:SX0042771903` and `QR-Code:https://…`. A code it cannot read will not scan either.
 4. **Check the native commands** are in the ZPL: `grep -o '\^B[CQEX][^^]*' label.zpl` shows `^BC`
    (Code 128), `^BQ` (QR), `^BE` (EAN-13), `^BX` (Data Matrix). A barcode that is missing there
-   stayed in the picture (see below), which prints too, but not on the printer's own dot grid.
+   stayed in the picture (see below): it prints, on the dot grid as part of the `^GFA` graphic,
+   but drawn by stationery, not by the printer's own barcode encoder.
 5. **Warnings**: `label.warnings` after `to_zpl` (or `to_png`) lists what a one-bit printer
    cannot print as it is.
 
@@ -100,7 +101,8 @@ possibly another QR mask. (Online, labelary.com renders a `.zpl` file.)
   dot grid. A barcode the printer could not draw as it is stays in the picture without a word: one
   rotated or clipped, paler than half grey, a module wider than 10 dots (a QR code sized with a
   large `width:` at 300 dpi), or a QR code of text outside ASCII. Size a native QR code by
-  `module_size:` (1 to 2 pt) and check the ZPL has its `^BQ` line.
+  `module_size:`, at most 720 / dpi points so a module is 10 dots or fewer (3.5 pt at 203 dpi,
+  2.4 pt at 300, 1.2 pt at 600), and check the ZPL has its `^BQ` line.
   Send it to port 9100: `TCPSocket.open(host, 9100) { |s| label.to_zpl(s) }`.
   From the shell: `stationery render label_pdf.rb --zpl --dpi 300`.
 - **Black and white only.** A thermal printer prints black or nothing. `monochrome dpi: 203` reports