stationery 0.1.0 → 0.3.0

data/lib/stationery/layout/list_item.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Layout
+    # One list entry: a marker right-aligned in the column before `indent`
+    # (`marker_gap` short of it) and a body flow beside it. Splits inside the
+    # body; the marker stays with the first fragment and never leaves its
+    # first line behind.
+    class ListItem < Node
+      attr_reader :marker, :body, :indent, :marker_gap
+
+      def initialize(marker, body, indent:, marker_gap:)
+        super()
+        @marker = marker
+        @body = body
+        @indent = indent
+        @marker_gap = marker_gap
+      end
+
+      def splittable? = @body.splittable?
+      def natural_width = @indent + @body.natural_width
+      def min_width = @indent + @body.min_width
+      def break_inside = @body.break_inside
+
+      def break_inside=(value)
+        @body.break_inside = value
+      end
+
+      def measure(width)
+        memoize_by_width(width) { [@marker ? @marker.measure(column) : 0, @body.measure(body_width(width))].max }
+      end
+
+      def paint(canvas, x, y, width, _height = nil, **)
+        if @marker
+          own = @marker.width_in(column)
+          @marker.paint(canvas, x + column - own, y, own)
+        end
+        @body.paint(canvas, x + @indent, y, body_width(width))
+      end
+
+      def split(width, height, fresh: false)
+        return [self, nil] if measure(width) <= height + EPSILON
+
+        head, tail = @body.split(body_width(width), height, fresh:)
+        return [nil, self] unless head
+
+        [with(@marker, head), tail && with(nil, tail).tap { |rest| rest.keep_with_next = keep_with_next }]
+      end
+
+      private
+
+      def column = [@indent - @marker_gap, 0].max
+      def body_width(width) = [width - @indent, 0].max
+      def with(marker, body) = self.class.new(marker, body, indent: @indent, marker_gap: @marker_gap)
+    end
+
+    # A drawn bullet (:disc, :circle or :square) sized to the text style and
+    # centred on its x-height.
+    class Bullet < Node
+      SIZE = 0.36
+      STROKE = 0.06
+
+      def initialize(shape, style:, context:)
+        super()
+        @shape = shape
+        @style = style
+        @font = context.book.resolve(style).first
+      end
+
+      def measure(_width) = @font.line_height(@style.size)
+      def fixed_width(_available) = diameter
+      def natural_width = diameter
+
+      def paint(canvas, x, y, _width, _height = nil, **)
+        radius = diameter / 2.0
+        cy = y + @font.ascender(@style.size) - (@font.x_height(@style.size) / 2.0)
+        case @shape
+        when :circle then canvas.circle(x + radius, cy, radius, stroke: @style.color, line_width: STROKE * @style.size)
+        when :square then canvas.fill_rect(x, cy - radius, diameter, diameter, color: @style.color)
+        else canvas.circle(x + radius, cy, radius, fill: @style.color)
+        end
+      end
+
+      private
+
+      def diameter = SIZE * @style.size
+    end
+  end
+end

data/lib/stationery/layout/mark.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Layout
+    # Takes up no space and paints nothing. Unlike a Spacer it survives a page
+    # break, so a standalone anchor is never dropped.
+    class Empty < Node
+      def measure(_width) = 0
+      def paint(*, **) = nil
+    end
+
+    # Names a node as a link target: its top is recorded as an anchor for each
+    # name where it is painted. When the node splits, the names stay with the
+    # first fragment.
+    class Mark < Node
+      attr_reader :child, :names
+
+      def self.standalone(name)
+        new(Empty.new, [name.to_s]).tap { |mark| mark.keep_with_next = true }
+      end
+
+      def initialize(child, names)
+        super()
+        @child = child
+        @names = names
+      end
+
+      def measure(width) = @child.measure(width)
+      def natural_width = @child.natural_width
+      def min_width = @child.min_width
+      def fixed_width(available) = @child.fixed_width(available)
+      def splittable? = @child.splittable?
+      def page_break? = @child.page_break?
+      def avoid_break? = @child.avoid_break?
+      def keep_with_next = @child.keep_with_next
+
+      def keep_with_next=(value)
+        @child.keep_with_next = value
+      end
+
+      def break_inside = @child.break_inside
+
+      def break_inside=(value)
+        @child.break_inside = value
+      end
+
+      def paint(canvas, x, y, width, height = nil, **)
+        @names.each { |name| canvas.anchor(name, y) }
+        @child.paint(canvas, x, y, width, height, **)
+      end
+
+      def split(width, height, **)
+        head, tail = @child.split(width, height, **)
+        [head && Mark.new(head, @names), tail]
+      end
+    end
+  end
+end

data/lib/stationery/layout/node.rb

@@ -19,7 +19,9 @@ module Stationery
     #
     # - measure(width)            → its height at that width
     # - paint(canvas, x, y, width, height = nil, **)
-    # - split(width, height)      → [part that fits, remainder] (nil for an empty side)
+    # - split(width, height, fresh: false)
+    #                             → [part that fits, remainder] (nil for an empty side);
+    #                               fresh: true when nothing is above it on a new page
     # - natural_width / min_width → its preferred and narrowest widths
     # - fixed_width(available)    → its own width, or nil when it fills the width
     class Node
@@ -29,18 +31,40 @@ module Stationery
       def paint(_canvas, _x, _y, _width, _height = nil, **) = raise(NotImplementedError, "#{self.class}#paint")
 
       def splittable? = false
+      # Moves whole to a fresh page before splitting; splits only when it does
+      # not fit there either.
+      def prefer_whole? = false
       def natural_width = 0
       def min_width = 0
       def fixed_width(_available) = nil
+      # The width this node is laid out at inside a parent of `available`.
+      def width_in(available) = fixed_width(available) || available
       def page_break? = false
 
-      def split(width, height)
+      def split(width, height, **)
         measure(width) <= height + EPSILON ? [self, nil] : [nil, self]
       end
 
       def avoid_break?
         break_inside == :avoid || !splittable?
       end
+
+      private
+
+      # Remembers a height per width: a page measures the same subtree for the
+      # flow splitter, keep_with_next and paint. Nodes are not changed after
+      # layout starts (Flow#<< forgets), and copies start with no measurements.
+      def memoize_by_width(width)
+        @measures ||= {}
+        @measures.fetch(width) { @measures[width] = yield }
+      end
+
+      def forget_measures = @measures = nil
+
+      def initialize_copy(source)
+        super
+        forget_measures
+      end
     end
   end
 end

data/lib/stationery/layout/paginator.rb

@@ -7,10 +7,12 @@ module Stationery
     class Paginator
       attr_reader :warnings
 
-      def initialize(resources:, page: {})
+      def initialize(resources:, page: {}, warnings: Warnings.new, debug: false, regions: nil)
         @resources = resources
+        @debug = debug
         @page_options = page
-        @warnings = []
+        @regions = regions
+        @warnings = warnings
       end
 
       def paginate(root)
@@ -18,9 +20,9 @@ module Stationery
         pages = []
         remaining = root
         while remaining
-          page = Page.new(**@page_options)
-          head, remaining = remaining.split(page.content_box.width, page.content_box.height, fresh: true)
-          place(page, head, pages.size + 1)
+          number = pages.size + 1
+          page, head, remaining = next_page(remaining, number)
+          place(page, head, number)
           pages << page
         end
         pages
@@ -28,13 +30,40 @@ module Stationery
 
       private
 
+      # A page whose regions differ when it is the last one tries the
+      # last-page box first: if everything left fits, it is the last page.
+      # Content that fits a normal page but not the last one moves partly on,
+      # so the last page follows.
+      def next_page(remaining, number)
+        page = new_page(number)
+        return [page, *fill(page, remaining)] unless @regions&.last_sensitive?(number)
+
+        last = new_page(number, last: true)
+        head, rest = fill(last, remaining)
+        return [last, head, nil] unless rest
+
+        normal_head, normal_rest = fill(page, remaining)
+        normal_rest ? [page, normal_head, normal_rest] : [page, head, rest]
+      end
+
+      def fill(page, remaining) = remaining.split(page.content_box.width, page.content_box.height, fresh: true)
+
+      def new_page(number, last: false)
+        page = Page.new(**@page_options, reserve: @regions ? @regions.reserve(number, last:) : [0, 0])
+        return page if page.reserve.sum < page.margin_box.height
+
+        raise ArgumentError, "header and footer leave no room for content on page #{number}"
+      end
+
       def place(page, head, number)
         return unless head
 
         box = page.content_box
         height = head.measure(box.width)
         @warnings << Overflow.new(page: number, height:, available: box.height) if height > box.height + EPSILON
-        head.paint(Canvas.new(page, @resources), box.x, box.y, box.width)
+        canvas = Canvas.new(page, @resources, debug: @debug)
+        head.paint(canvas, box.x, box.y, box.width)
+        canvas.debug_rect(box.x, box.y, box.width, box.height, :page)
       end
     end
   end

data/lib/stationery/layout/positioned.rb

@@ -17,7 +17,9 @@ module Stationery
       def measure(_width) = 0
 
       def paint(canvas, _x, _y, width, _height = nil, **)
-        @node.paint(canvas, @x, @y, @width || @node.fixed_width(width) || width)
+        width = @width || @node.fixed_width(width) || width
+        @node.paint(canvas, @x, @y, width)
+        canvas.debug_rect(@x, @y, width, @node.measure(width), :positioned) if canvas.debug?
       end
     end
   end

data/lib/stationery/layout/row.rb

@@ -4,8 +4,11 @@ module Stationery
   module Layout
     # Columns side by side. A column's `width:` is points (a number above 1),
     # a fraction of the row (0.5), :auto (its natural width) or nil (an equal
-    # share of what is left). The row is as tall as its tallest column, stretches
-    # every column to that height and never splits.
+    # share of what is left). The row is as tall as its tallest column and
+    # stretches every column to that height. Like a box it moves to the next
+    # page whole when it fits there and otherwise splits every column at the
+    # same line; a column that ends early continues as an empty fragment so
+    # the backgrounds stay aligned.
     class Row < Node
       attr_reader :columns
 
@@ -19,15 +22,35 @@ module Stationery
       def natural_width = @columns.sum(&:natural_width) + gaps
       def min_width = @columns.sum(&:min_width) + gaps
 
+      def splittable? = @columns.all?(&:splittable?)
+      def prefer_whole? = break_inside.nil? && splittable?
+
+      def split(width, height, fresh: false)
+        return [self, nil] if measure(width) <= height + EPSILON
+
+        parts = @columns.zip(column_widths(width)).map do |column, w|
+          next [column, nil] if column.measure(w) <= height + EPSILON
+
+          column.avoid_break? ? [nil, column] : column.split(w, height, fresh:)
+        end
+        return [nil, self] if parts.any? { |head, _| head.nil? }
+
+        heads = parts.map { |head, _| head.with_open(:bottom) }
+        tails = parts.zip(@columns).map { |(_, tail), column| tail || column.continued }
+        [with_columns(heads).tap { |row| row.keep_with_next = nil }, with_columns(tails)]
+      end
+
+      def with_columns(columns) = dup.replace_columns(columns)
+
       def measure(width)
-        @columns.zip(column_widths(width)).map { |column, w| column.measure(w) }.max || 0
+        memoize_by_width(width) { @columns.zip(column_widths(width)).map { |column, w| column.measure(w) }.max || 0 }
       end
 
       def paint(canvas, x, y, width, height = nil, **)
         height ||= measure(width)
         left = x
         @columns.zip(column_widths(width)).each do |column, w|
-          column.paint(canvas, left, y, w, height, valign: @align)
+          column.paint(canvas, left, y, w, height, valign: @align, debug_kind: :column)
           left += w + @gap
         end
       end
@@ -42,6 +65,13 @@ module Stationery
         widths
       end
 
+      protected
+
+      def replace_columns(columns)
+        @columns = columns
+        self
+      end
+
       private
 
       def gaps = @gap * [@columns.size - 1, 0].max

data/lib/stationery/layout/svg.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Layout
+    # A vector drawing at a fixed size: `width:` and/or `height:` (the other
+    # follows the viewBox's aspect ratio), never wider than the space given.
+    class Svg < Node
+      # `context` gives SVG text its font book and default family.
+      def initialize(document, width: nil, height: nil, color: "#000000", context: nil)
+        super()
+        @document = document
+        @context = context
+        @width = width
+        @height = height
+        @color = color
+      end
+
+      def size(available)
+        width, height = requested
+        return [width, height] if width <= available
+
+        [available, height * available / width]
+      end
+
+      def measure(width) = size(width)[1]
+      def fixed_width(available) = size(available)[0]
+      def natural_width = requested[0]
+
+      def paint(canvas, x, y, width, _height = nil, **)
+        w, h = size(width)
+        @document.draw(canvas, x:, y:, width: w, height: h, color: @color, book: @context&.book,
+                               family: @context&.style&.family)
+        canvas.debug_rect(x, y, w, h, :image)
+      end
+
+      private
+
+      def requested
+        aspect = @document.aspect
+        if @width && @height then [@width, @height]
+        elsif @width then [@width, @width / aspect]
+        elsif @height then [@height * aspect, @height]
+        else @document.view_box.last(2)
+        end
+      end
+    end
+  end
+end

data/lib/stationery/layout/table/cell.rb

@@ -9,24 +9,39 @@ module Stationery
         TEXT_OPTIONS = { size: :size, color: :color, weight: :weight, style: :style, font: :family,
                          letter_spacing: :letter_spacing }.freeze
 
-        attr_reader :content, :options
+        attr_reader :content, :options, :colspan, :rowspan
 
-        def initialize(content, options)
+        def initialize(content, options, colspan: 1, rowspan: 1)
           @content = content
           @options = options.dup
+          @colspan = colspan
+          @rowspan = rowspan
         end
 
         def node(context)
           @node ||= @content.is_a?(Node) ? @content : text_node(context)
         end
 
-        def padding = Geometry.box(@options[:padding])
+        # The same cell holding another node, as a row split into two parts needs.
+        def with_content(node) = Cell.new(node, @options, colspan:, rowspan:)
+
+        # Changes an option and forgets the node built from the old ones.
+        def []=(name, value)
+          @options[name] = value
+          @node = nil
+          @padding = nil
+          @metrics = nil
+        end
+
+        def padding = @padding ||= Geometry.box(@options[:padding])
         def horizontal = padding[1] + padding[3]
         def vertical = padding[0] + padding[2]
 
-        def measure(context, width) = node(context).measure([width - horizontal, 0].max) + vertical
-        def natural_width(context) = node(context).natural_width + horizontal
-        def min_width(context) = node(context).min_width + horizontal
+        # Heights per width and the natural and minimum widths are remembered:
+        # every fragment of a table split across pages measures the same cells.
+        def measure(context, width) = metric(width) { node(context).measure([width - horizontal, 0].max) + vertical }
+        def natural_width(context) = metric(:natural) { node(context).natural_width + horizontal }
+        def min_width(context) = metric(:min) { node(context).min_width + horizontal }
 
         # Backgrounds overlap the next cell by SEAM so viewers do not show
         # hairline gaps between neighbouring fills.
@@ -39,10 +54,16 @@ module Stationery
           end
           paint_content(canvas, context, rect)
           paint_borders(canvas, rect)
+          paint_debug(canvas, rect) if canvas.debug?
         end
 
         private
 
+        def metric(key)
+          @metrics ||= {}
+          @metrics.fetch(key) { @metrics[key] = yield }
+        end
+
         def text_node(context)
           style = context.style.with(**TEXT_OPTIONS.filter_map do |key, attr|
             [attr, @options[key]] if @options.key?(key)
@@ -68,6 +89,12 @@ module Stationery
           content.paint(canvas, left, inner.y + offset, own || inner.width)
         end
 
+        def paint_debug(canvas, rect)
+          canvas.debug_rect(rect.x, rect.y, rect.width, rect.height, :cell)
+          inner = rect.inset(*padding)
+          canvas.debug_rect(inner.x, inner.y, inner.width, inner.height, :cell_padding)
+        end
+
         def paint_borders(canvas, rect)
           width = @options[:border_width]
           return if width.nil? || width.zero?

data/lib/stationery/layout/table/grid.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Layout
+    class Table < Node
+      # Places cells that span columns and rows the way HTML does: each row
+      # lists only the cells it starts, and a cell skips slots a rowspan from
+      # above already covers. Rowspans running past the last row are clamped.
+      class Grid
+        Placement = Data.define(:cell, :row, :column, :colspan, :rowspan) do
+          def columns = column...(column + colspan)
+          def rows = row...(row + rowspan)
+        end
+
+        attr_reader :placements, :row_count, :column_count
+
+        def initialize(rows)
+          @row_count = rows.size
+          @slots = Array.new(@row_count) { [] }
+          @placements = rows.each_with_index.flat_map { |row, r| place(row, r) }
+          @column_count = @placements.map { |p| p.columns.end }.max || 0
+        end
+
+        def at(row, column) = row.negative? || column.negative? ? nil : @slots.dig(row, column)&.cell
+
+        # Row indexes a horizontal cut can fall before without splitting a rowspan.
+        def boundaries
+          @boundaries ||= begin
+            inside = Array.new(row_count + 1, false)
+            @placements.each do |p|
+              ((p.row + 1)...p.rows.end).each { |r| inside[r] = true } if p.rowspan > 1
+            end
+            (0..row_count).reject { |r| inside[r] }.freeze
+          end
+        end
+
+        # A metric per column: the largest single-column value, then the excess
+        # of a spanning cell over its columns spread evenly across them.
+        def column_metric
+          values = Array.new(column_count, 0)
+          single, spanning = @placements.partition { |p| p.colspan == 1 }
+          single.each do |p|
+            value = yield(p)
+            values[p.column] = value if value > values[p.column]
+          end
+          spanning.each do |p|
+            excess = yield(p) - values[p.columns].sum
+            p.columns.each { |c| values[c] += excess.fdiv(p.colspan) } if excess.positive?
+          end
+          values
+        end
+
+        # Each row's height from its cells measured at their spanned width; a
+        # rowspan taller than its rows adds the excess to its last row.
+        def row_heights(widths)
+          heights = Array.new(row_count, 0)
+          single, spanning = @placements.partition { |p| p.rowspan == 1 }
+          single.each do |p|
+            height = yield(p, p.colspan == 1 ? widths[p.column] : widths[p.columns].sum)
+            heights[p.row] = height if height > heights[p.row]
+          end
+          spanning.each do |p|
+            excess = yield(p, widths[p.columns].sum) - heights[p.rows].sum
+            heights[p.rows.end - 1] += excess if excess.positive?
+          end
+          heights
+        end
+
+        private
+
+        def place(row, r)
+          column = 0
+          slots = @slots[r]
+          row.map do |cell|
+            column += 1 while slots[column]
+            placement = Placement.new(cell, r, column, cell.colspan, cell.rowspan.clamp(1, row_count - r))
+            occupy(placement)
+            column += cell.colspan
+            placement
+          end
+        end
+
+        def occupy(placement)
+          if placement.colspan == 1 && placement.rowspan == 1
+            @slots[placement.row][placement.column] = placement
+          else
+            placement.rows.each { |pr| placement.columns.each { |pc| @slots[pr][pc] = placement } }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/stationery/layout/table/row_splitter.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Layout
+    class Table < Node
+      # Cuts one row too tall for the space left: each cell's content splits at
+      # that height, what fits stays above the cut and the rest starts the row
+      # again below it. A cell with nothing on one side becomes an empty cell
+      # there, so backgrounds and borders run the full height of both parts.
+      class RowSplitter
+        def initialize(placements, widths:, context:)
+          @placements = placements
+          @widths = widths
+          @context = context
+        end
+
+        # [head cells, tail cells], or nil when no cell fits anything above the cut.
+        def call(height)
+          parts = @placements.map { |placement| [placement.cell, *cut(placement, height)] }
+          return if parts.none? { |_, head| head }
+
+          [parts.map { |cell, head| cell.with_content(head || Flow.new) },
+           parts.map { |cell, _, tail| cell.with_content(tail || Flow.new) }]
+        end
+
+        private
+
+        def cut(placement, height)
+          cell = placement.cell
+          width = [@widths[placement.columns].sum - cell.horizontal, 0].max
+          cell.node(@context).split(width, height - cell.vertical)
+        end
+      end
+    end
+  end
+end

data/lib/stationery/layout/table/selection.rb

@@ -24,7 +24,7 @@ module Stationery
         def columns(spec) = Selection.new(@table, @rows, @columns & Selection.indexes(spec, @table.column_count))
         alias column columns
 
-        def cells = @rows.flat_map { |r| @columns.filter_map { |c| @table.cell(r, c) } }
+        def cells = @rows.flat_map { |r| @columns.filter_map { |c| @table.cell(r, c) } }.uniq
 
         def set(**attributes)
           attributes.each { |name, value| public_send(:"#{name}=", value) }
@@ -33,7 +33,8 @@ module Stationery
 
         ATTRIBUTES.each do |name|
           define_method(:"#{name}=") do |value|
-            cells.each { |cell| cell.options[name] = value }
+            cells.each { |cell| cell[name] = value }
+            @table.invalidate!
           end
         end