stationery 0.1.0

data/lib/stationery/layout/box.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Layout
+    # A container with padding, background, border and corner radius. Boxes
+    # move to the next page whole. A fixed-height box can truncate or shrink
+    # text that does not fit (`overflow:`).
+    class Box < Node
+      BORDER = { width: 1, color: "#000000", sides: %i[top right bottom left] }.freeze
+
+      attr_reader :content, :width_spec
+
+      def initialize(content = Flow.new, padding: 0, background: nil, border: nil, radius: 0, width: nil,
+                     height: nil, overflow: :visible, valign: :top, opacity: nil)
+        super()
+        @content = content
+        @padding = Geometry.box(padding)
+        @background = background
+        @border = border && BORDER.merge(border)
+        @radius = radius
+        @width_spec = width
+        @height = height
+        @overflow = overflow
+        @valign = valign
+        @opacity = opacity
+      end
+
+      def natural_width
+        @width_spec.is_a?(Numeric) && @width_spec > 1 ? @width_spec : @content.natural_width + horizontal
+      end
+
+      def min_width = @content.min_width + horizontal
+
+      def fixed_width(available)
+        case @width_spec
+        when :auto then [natural_width, available].min
+        when Float then @width_spec <= 1 ? available * @width_spec : @width_spec
+        when Numeric then @width_spec
+        end
+      end
+
+      def measure(width)
+        @height || (@content.measure(inner_width(width)) + vertical)
+      end
+
+      def paint(canvas, x, y, width, height = nil, valign: nil, **)
+        height ||= measure(width)
+        paint_background(canvas, x, y, width, height)
+        paint_border(canvas, x, y, width, height)
+        paint_content(canvas, x, y, width, height, valign || @valign)
+      end
+
+      private
+
+      def insets
+        border = @border ? @border[:width] : 0
+        top, right, bottom, left = @padding
+        sides = @border ? @border[:sides] : []
+        [top + (sides.include?(:top) ? border : 0), right + (sides.include?(:right) ? border : 0),
+         bottom + (sides.include?(:bottom) ? border : 0), left + (sides.include?(:left) ? border : 0)]
+      end
+
+      def horizontal = insets[1] + insets[3]
+      def vertical = insets[0] + insets[2]
+      def inner_width(width) = [width - horizontal, 0].max
+
+      def paint_background(canvas, x, y, width, height)
+        return unless @background
+
+        canvas.rounded_rect(x, y, width, height, radius: @radius, fill: @background, opacity: @opacity)
+      end
+
+      def paint_border(canvas, x, y, width, height)
+        return unless @border
+
+        stroke = @border[:width]
+        if @border[:sides].size == 4 && @radius.positive?
+          half = stroke / 2.0
+          canvas.rounded_rect(x + half, y + half, width - stroke, height - stroke,
+                              radius: @radius, stroke: @border[:color], line_width: stroke)
+        else
+          @border[:sides].each { |side| border_side(canvas, side, Rect.new(x, y, width, height), stroke) }
+        end
+      end
+
+      def border_side(canvas, side, rect, stroke)
+        half = stroke / 2.0
+        x1, y1, x2, y2 = case side
+                         when :top then [rect.x, rect.y + half, rect.right, rect.y + half]
+                         when :bottom then [rect.x, rect.bottom - half, rect.right, rect.bottom - half]
+                         when :left then [rect.x + half, rect.y, rect.x + half, rect.bottom]
+                         else [rect.right - half, rect.y, rect.right - half, rect.bottom]
+                         end
+        canvas.line(x1, y1, x2, y2, color: @border[:color], width: stroke)
+      end
+
+      def paint_content(canvas, x, y, width, height, valign)
+        top, _right, _bottom, left = insets
+        inner = Rect.new(x, y, width, height).inset(*insets)
+        content = fitted(inner)
+        used = content.measure(inner.width)
+        offset = Geometry.align_offset(if valign == :middle
+                                         :center
+                                       else
+                                         (valign == :bottom ? :right : :left)
+                                       end,
+                                       inner.height, used)
+        paint_inner = -> { content.paint(canvas, x + left, y + top + [offset, 0].max, inner.width) }
+        if @overflow == :visible
+          paint_inner.call
+        else
+          canvas.clip(inner.x, inner.y, inner.width, inner.height) do
+            paint_inner.call
+          end
+        end
+      end
+
+      def fitted(inner)
+        return @content if @overflow == :visible || @height.nil? || @content.measure(inner.width) <= inner.height
+        return shrunk(inner) if @overflow == :shrink_to_fit && shrinkable?
+
+        @content.split(inner.width, inner.height).first || Flow.new
+      end
+
+      def shrinkable?
+        @content.is_a?(Flow) && @content.children.size == 1 && @content.children.first.respond_to?(:fit)
+      end
+
+      def shrunk(inner)
+        @content.with_children([@content.children.first.fit(inner.width, inner.height, overflow: :shrink_to_fit)])
+      end
+    end
+  end
+end

data/lib/stationery/layout/flow.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Layout
+    # Children stacked top to bottom: the document body and every box's
+    # content. Splits across pages: a splittable child continues on the next
+    # page, anything else moves there whole, a spacer at the break is dropped
+    # and a child marked keep_with_next moves with its successor.
+    class Flow < Node
+      attr_reader :children, :gap, :align
+
+      def initialize(children = [], gap: 0, align: :left)
+        super()
+        @children = children
+        @gap = gap
+        @align = align
+      end
+
+      def <<(child)
+        @children << child
+        self
+      end
+
+      def splittable? = true
+      def natural_width = @children.map(&:natural_width).max || 0
+      def min_width = @children.map(&:min_width).max || 0
+
+      def measure(width)
+        visible = @children.reject(&:page_break?)
+        visible.sum { |child| child.measure(width) } + (@gap * [visible.size - 1, 0].max)
+      end
+
+      def paint(canvas, x, y, width, _height = nil, **)
+        cursor = y
+        @children.reject(&:page_break?).each_with_index do |child, index|
+          cursor += @gap unless index.zero?
+          own = child.fixed_width(width)
+          left = own ? x + Geometry.align_offset(@align, width, own) : x
+          child.paint(canvas, left, cursor, own || width)
+          cursor += child.measure(width)
+        end
+      end
+
+      def split(width, height, fresh: false)
+        Splitter.new(self, width, height, fresh).call
+      end
+
+      def with_children(children)
+        self.class.new(children, gap: @gap, align: @align)
+      end
+    end
+
+    # One pass of Flow#split, kept apart so the rules read top to bottom.
+    class Flow
+      class Splitter
+        def initialize(flow, width, height, fresh)
+          @flow = flow
+          @width = width
+          @height = height
+          @fresh = fresh
+          @placed = []
+          @used = 0
+        end
+
+        def call
+          children = @flow.children
+          children.each_with_index do |child, index|
+            rest = children.drop(index + 1)
+            result = place(child, rest)
+            return result if result
+          end
+          [part(@placed), nil]
+        end
+
+        private
+
+        def place(child, rest)
+          return page_break(rest) if child.page_break?
+
+          gap = @placed.empty? ? 0 : @flow.gap
+          remaining = @height - @used - gap
+          height = child.measure(@width)
+          return fits(child, height + gap, remaining - height, rest) if height <= remaining + EPSILON
+          return [part(@placed), part(rest)] if child.is_a?(Spacer)
+
+          split_or_move(child, remaining, rest)
+        end
+
+        def page_break(rest)
+          return nil if @placed.empty?
+
+          [part(@placed), part(rest)]
+        end
+
+        def fits(child, consumed, left_after, rest)
+          if child.keep_with_next && rest.any? && !@placed.empty? && rest.first.split(@width, left_after).first.nil?
+            return [part(@placed), part([child, *rest])]
+          end
+
+          @placed << child
+          @used += consumed
+          nil
+        end
+
+        def split_or_move(child, remaining, rest)
+          unless child.avoid_break?
+            head, tail = child.split(@width, remaining)
+            return [part(@placed + [head]), part([tail, *rest])] if head
+          end
+          return [part([child]), part(rest)] if @placed.empty? && @fresh
+
+          @placed.empty? ? [nil, part([child, *rest])] : [part(@placed), part([child, *rest])]
+        end
+
+        def part(children)
+          children.empty? ? nil : @flow.with_children(children)
+        end
+      end
+    end
+  end
+end

data/lib/stationery/layout/image.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Layout
+    # An image sized by width, height, both, or a box to fit into (aspect
+    # preserved), never wider than the space it is given. One pixel is one
+    # point when no size is given.
+    class Image < Node
+      def initialize(source, width: nil, height: nil, fit: nil, opacity: nil)
+        super()
+        @image = source.respond_to?(:build) ? source : Images.load(source)
+        @width = width
+        @height = height
+        @fit = fit
+        @opacity = opacity
+      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 min_width = 0
+
+      def paint(canvas, x, y, width, _height = nil, **)
+        w, h = size(width)
+        canvas.image(@image, x:, y:, width: w, height: h, opacity: @opacity)
+      end
+
+      private
+
+      def requested
+        iw = @image.width.to_f
+        ih = @image.height.to_f
+        if @fit
+          scale = [@fit[0] / iw, @fit[1] / ih].min
+          [iw * scale, ih * scale].map { |v| tidy(v) }
+        elsif @width && @height then [@width, @height]
+        elsif @width then [@width, tidy(ih * @width / iw)]
+        elsif @height then [tidy(iw * @height / ih), @height]
+        else [@image.width, @image.height]
+        end
+      end
+
+      def tidy(value) = value.round(6)
+    end
+  end
+end

data/lib/stationery/layout/leaves.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Layout
+    # A filled horizontal bar: dividers and accent bands.
+    class Rule < Node
+      def initialize(height: 1, color: "#000000", width: nil, radius: 0)
+        super()
+        @height = height
+        @color = color
+        @width = width
+        @radius = radius
+      end
+
+      def measure(_width) = @height
+      def fixed_width(available) = @width && [@width, available].min
+
+      def paint(canvas, x, y, width, _height = nil, **)
+        canvas.rounded_rect(x, y, @width || width, @height, radius: @radius, fill: @color)
+      end
+    end
+
+    # Vertical space. Dropped when it lands on a page break.
+    class Spacer < Node
+      def initialize(height)
+        super()
+        @height = height
+      end
+
+      def measure(_width) = @height
+      def paint(*, **) = nil
+    end
+
+    # Forces the content after it onto a new page.
+    class PageBreak < Node
+      def measure(_width) = 0
+      def paint(*, **) = nil
+      def page_break? = true
+    end
+
+    # Reserves `height` and hands a block the canvas, clipped to the reserved
+    # rectangle, and that rectangle in page coordinates.
+    class CanvasNode < Node
+      def initialize(height:, &block)
+        super()
+        @height = height
+        @block = block
+      end
+
+      def measure(_width) = @height
+
+      def paint(canvas, x, y, width, _height = nil, **)
+        rect = Rect.new(x, y, width, @height)
+        canvas.clip(x, y, width, @height) { @block.call(canvas, rect) }
+      end
+    end
+  end
+end

data/lib/stationery/layout/node.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Layout
+    EPSILON = 0.0001
+
+    # What text nodes need to measure: the document's fonts and the base style.
+    Context = Data.define(:book, :style)
+
+    # A node placed taller than the space a page had for it.
+    Overflow = Data.define(:page, :height, :available) do
+      def message
+        format("content %<height>.1fpt tall placed on page %<page>d with %<available>.1fpt available",
+               height:, page:, available:)
+      end
+    end
+
+    # The layout protocol. Every node can:
+    #
+    # - 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)
+    # - natural_width / min_width → its preferred and narrowest widths
+    # - fixed_width(available)    → its own width, or nil when it fills the width
+    class Node
+      attr_accessor :keep_with_next, :break_inside
+
+      def measure(_width) = raise(NotImplementedError, "#{self.class} must implement measure")
+      def paint(_canvas, _x, _y, _width, _height = nil, **) = raise(NotImplementedError, "#{self.class}#paint")
+
+      def splittable? = false
+      def natural_width = 0
+      def min_width = 0
+      def fixed_width(_available) = nil
+      def page_break? = false
+
+      def split(width, height)
+        measure(width) <= height + EPSILON ? [self, nil] : [nil, self]
+      end
+
+      def avoid_break?
+        break_inside == :avoid || !splittable?
+      end
+    end
+  end
+end

data/lib/stationery/layout/paginator.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Layout
+    # Lays a node tree out onto as many pages as it needs. Content placed
+    # taller than a page is kept (never raised on) and recorded in #warnings.
+    class Paginator
+      attr_reader :warnings
+
+      def initialize(resources:, page: {})
+        @resources = resources
+        @page_options = page
+        @warnings = []
+      end
+
+      def paginate(root)
+        root = Flow.new([root]) unless root.is_a?(Flow)
+        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)
+          pages << page
+        end
+        pages
+      end
+
+      private
+
+      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)
+      end
+    end
+  end
+end

data/lib/stationery/layout/positioned.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Layout
+    # A node painted at a fixed page position instead of in the flow; it takes
+    # up no flow height. Used for page-template headers, footers and
+    # backgrounds, and for content that floats over the page.
+    class Positioned < Node
+      def initialize(node, x:, y:, width: nil)
+        super()
+        @node = node
+        @x = x
+        @y = y
+        @width = width
+      end
+
+      def measure(_width) = 0
+
+      def paint(canvas, _x, _y, width, _height = nil, **)
+        @node.paint(canvas, @x, @y, @width || @node.fixed_width(width) || width)
+      end
+    end
+  end
+end

data/lib/stationery/layout/row.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+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.
+    class Row < Node
+      attr_reader :columns
+
+      def initialize(columns, gap: 0, align: :top)
+        super()
+        @columns = columns
+        @gap = gap
+        @align = align
+      end
+
+      def natural_width = @columns.sum(&:natural_width) + gaps
+      def min_width = @columns.sum(&:min_width) + gaps
+
+      def measure(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)
+          left += w + @gap
+        end
+      end
+
+      def column_widths(width)
+        available = [width - gaps, 0].max
+        widths = @columns.map { |column| declared(column, available) }
+        shrink_auto(widths, available)
+        shared = @columns.each_index.select { |i| widths[i].nil? }
+        rest = [available - widths.compact.sum, 0].max
+        shared.each { |i| widths[i] = rest / shared.size }
+        widths
+      end
+
+      private
+
+      def gaps = @gap * [@columns.size - 1, 0].max
+
+      def declared(column, available)
+        spec = column.respond_to?(:width_spec) ? column.width_spec : nil
+        case spec
+        when nil then nil
+        when :auto then [column.natural_width, available].min
+        when Float then spec <= 1 ? available * spec : spec
+        else spec
+        end
+      end
+
+      def shrink_auto(widths, available)
+        excess = widths.compact.sum - available
+        autos = @columns.each_index.select do |i|
+          @columns[i].respond_to?(:width_spec) && @columns[i].width_spec == :auto
+        end
+        return unless excess.positive? && autos.any?
+
+        total = autos.sum { |i| widths[i] }
+        autos.each { |i| widths[i] -= excess * widths[i] / total }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Layout
+    class Table < Node
+      # One table cell: content (a String, markup String or layout node) and its
+      # options, which selections change until the table is laid out.
+      class Cell
+        TEXT_OPTIONS = { size: :size, color: :color, weight: :weight, style: :style, font: :family,
+                         letter_spacing: :letter_spacing }.freeze
+
+        attr_reader :content, :options
+
+        def initialize(content, options)
+          @content = content
+          @options = options.dup
+        end
+
+        def node(context)
+          @node ||= @content.is_a?(Node) ? @content : text_node(context)
+        end
+
+        def 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
+
+        # Backgrounds overlap the next cell by SEAM so viewers do not show
+        # hairline gaps between neighbouring fills.
+        SEAM = 0.5
+
+        def paint(canvas, context, rect, last_column: true, last_row: true)
+          if @options[:background]
+            canvas.fill_rect(rect.x, rect.y, rect.width + (last_column ? 0 : SEAM),
+                             rect.height + (last_row ? 0 : SEAM), color: @options[:background])
+          end
+          paint_content(canvas, context, rect)
+          paint_borders(canvas, rect)
+        end
+
+        private
+
+        def text_node(context)
+          style = context.style.with(**TEXT_OPTIONS.filter_map do |key, attr|
+            [attr, @options[key]] if @options.key?(key)
+          end.to_h)
+          source = @content.to_s
+          runs = if @options[:markup]
+                   ::Stationery::Text::Markup.parse(source, style)
+                 else
+                   [::Stationery::Text::Run.new(source, style)]
+                 end
+          Text.new(runs, context: context.with(style:), align: @options[:align] || :left,
+                         leading: @options[:leading] || 0)
+        end
+
+        def paint_content(canvas, context, rect)
+          inner = rect.inset(*padding)
+          content = node(context)
+          used = content.measure(inner.width)
+          valign = { middle: :center, bottom: :right }.fetch(@options[:valign], :left)
+          offset = [Geometry.align_offset(valign, inner.height, used), 0].max
+          own = content.fixed_width(inner.width)
+          left = own ? inner.x + Geometry.align_offset(@options[:align] || :left, inner.width, own) : inner.x
+          content.paint(canvas, left, inner.y + offset, own || inner.width)
+        end
+
+        def paint_borders(canvas, rect)
+          width = @options[:border_width]
+          return if width.nil? || width.zero?
+
+          color = @options[:border_color]
+          Array(@options[:borders]).each do |side|
+            x1, y1, x2, y2 = edge(side, rect)
+            canvas.line(x1, y1, x2, y2, color:, width:)
+          end
+        end
+
+        def edge(side, rect)
+          case side
+          when :top then [rect.x, rect.y, rect.right, rect.y]
+          when :bottom then [rect.x, rect.bottom, rect.right, rect.bottom]
+          when :left then [rect.x, rect.y, rect.x, rect.bottom]
+          else [rect.right, rect.y, rect.right, rect.bottom]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Layout
+    class Table < Node
+      # Rows, columns or single cells picked out of a table to style together:
+      #
+      #   t.row(0).background = "#111"
+      #   t.columns(1..).align = :right
+      #   t.row(-1).columns(2..).borders = [:top]
+      class Selection
+        ATTRIBUTES = %i[background color weight style size align valign borders border_color border_width
+                        padding font markup leading letter_spacing].freeze
+
+        def initialize(table, rows, columns)
+          @table = table
+          @rows = rows
+          @columns = columns
+        end
+
+        def rows(spec) = Selection.new(@table, @rows & Selection.indexes(spec, @table.row_count), @columns)
+        alias row rows
+
+        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 set(**attributes)
+          attributes.each { |name, value| public_send(:"#{name}=", value) }
+          self
+        end
+
+        ATTRIBUTES.each do |name|
+          define_method(:"#{name}=") do |value|
+            cells.each { |cell| cell.options[name] = value }
+          end
+        end
+
+        def self.indexes(spec, count)
+          all = (0...count).to_a
+          case spec
+          when Integer then [all[spec]].compact
+          when Range then Array(all[spec])
+          when Array then spec.flat_map { |s| indexes(s, count) }
+          else raise ArgumentError, "select rows or columns with an Integer, Range or Array, not #{spec.inspect}"
+          end
+        end
+      end
+    end
+  end
+end