stationery 0.1.0 → 0.3.0

data/lib/generators/stationery/fonts_generator.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "stationery"
+
+module Stationery
+  module Generators
+    # bin/rails generate stationery:fonts noto_sans liberation_serif [--into vendor/fonts] [--force]
+    class FontsGenerator < ::Rails::Generators::Base
+      desc "Install pinned, SHA-256-checked font packs (#{Stationery::Fonts.catalog.map(&:key).join(", ")})"
+      argument :names, type: :array, banner: "PACK PACK"
+      class_option :into, type: :string, default: Stationery::Fonts::DEFAULT_DIR, desc: "Where packs live"
+      class_option :force, type: :boolean, default: false, desc: "Replace files that are already installed"
+
+      def install_packs
+        dir = File.expand_path(options[:into], destination_root)
+        names.each do |name|
+          Stationery::Fonts.install(name, into: dir, force: options[:force], out: $stdout)
+          say "Use it with: #{Stationery::Fonts.usage(name, options[:into]).last}"
+        end
+      end
+    end
+  end
+end

data/lib/stationery/builder.rb

@@ -4,7 +4,8 @@ module Stationery
   # Collects the nodes a component tree describes. Holds the container stack
   # (where the next node goes) and the text defaults in effect.
   class Builder
-    STYLE_KEYS = %i[size color weight style letter_spacing underline strikethrough link opacity].freeze
+    STYLE_KEYS = %i[size color weight style letter_spacing underline strikethrough link opacity kerning
+                    ligatures].freeze
 
     # Collects a row's columns; anything that is not already a column box is
     # wrapped in one.
@@ -19,13 +20,33 @@ module Stationery
       end
     end
 
-    attr_reader :root, :book
+    # Collects a list's items: every node added becomes one item.
+    class Items
+      attr_reader :nodes
+
+      def initialize = @nodes = []
+
+      def <<(node)
+        @nodes << node
+        self
+      end
+    end
+
+    attr_reader :root, :book, :list_depth
 
     def initialize(book:, text: {})
       @book = book
       @root = Layout::Flow.new
       @containers = [@root]
       @text = [text]
+      @list_depth = 0
+    end
+
+    def nested_list
+      @list_depth += 1
+      yield
+    ensure
+      @list_depth -= 1
     end
 
     def add(node)
@@ -49,10 +70,12 @@ module Stationery
     end
 
     def text_defaults = @text.last
+    def outline = @outline ||= Outline.new
+    def warnings = @book.warnings
 
     def style(options = {})
       options = text_defaults.merge(options)
-      family = options[:font] || @book.families.keys.first || "default"
+      family = options[:font] || @book.families.keys.first || Fonts::Bundled::DEFAULT
       Text::Style.new(family: family.to_s, **options.slice(*STYLE_KEYS))
     end
 

data/lib/stationery/canvas/debug.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Stationery
+  class Canvas
+    # Layout outlines for `to_pdf(debug: true)`: a thin stroke around each
+    # layout rectangle, coloured by what drew it. `debug:` is true (every
+    # kind) or an Array of kinds.
+    module Debug
+      DEBUG_COLORS = {
+        box: "#E11D48", padding: "#E11D48", column: "#2563EB", cell: "#16A34A", cell_padding: "#16A34A",
+        flow: "#9CA3AF", positioned: "#DB2777", image: "#0D9488", page: "#06B6D4", region: "#0EA5E9"
+      }.freeze
+      DEBUG_DASHES = { padding: [2, 2], cell_padding: [2, 2], flow: [1, 2] }.freeze
+
+      def debug? = @debug == true || (@debug.is_a?(Array) && @debug.any?)
+
+      def debug_rect(x, y, w, h, kind)
+        return unless @debug == true || (@debug.is_a?(Array) && @debug.include?(kind))
+
+        color = DEBUG_COLORS.fetch(kind) { raise ArgumentError, "unknown debug kind: #{kind.inspect}" }
+        rounded_rect(x + 0.25, y + 0.25, w - 0.5, h - 0.5, radius: 0, stroke: color, line_width: 0.5,
+                                                           dash: DEBUG_DASHES[kind])
+      end
+    end
+  end
+end

data/lib/stationery/canvas/path.rb

@@ -31,20 +31,21 @@ module Stationery
         close
       end
 
+      # r is one radius for every corner or [top_left, top_right, bottom_right,
+      # bottom_left]; radii are scaled down together until each side fits.
       def rounded_rect(x, y, w, h, r)
-        r = [r, w / 2.0, h / 2.0].min
-        return rect(x, y, w, h) if r <= 0
+        tl, tr, br, bl = corner_radii(r, w, h)
+        return rect(x, y, w, h) if [tl, tr, br, bl].none?(&:positive?)
 
-        k = r * KAPPA
-        move_to(x + r, y)
-        line_to(x + w - r, y)
-        curve_to(x + w - r + k, y, x + w, y + r - k, x + w, y + r)
-        line_to(x + w, y + h - r)
-        curve_to(x + w, y + h - r + k, x + w - r + k, y + h, x + w - r, y + h)
-        line_to(x + r, y + h)
-        curve_to(x + r - k, y + h, x, y + h - r + k, x, y + h - r)
-        line_to(x, y + r)
-        curve_to(x, y + r - k, x + r - k, y, x + r, y)
+        move_to(x + tl, y)
+        line_to(x + w - tr, y)
+        curve_to(x + w - tr + (tr * KAPPA), y, x + w, y + tr - (tr * KAPPA), x + w, y + tr) if tr.positive?
+        line_to(x + w, y + h - br)
+        curve_to(x + w, y + h - br + (br * KAPPA), x + w - br + (br * KAPPA), y + h, x + w - br, y + h) if br.positive?
+        line_to(x + bl, y + h)
+        curve_to(x + bl - (bl * KAPPA), y + h, x, y + h - bl + (bl * KAPPA), x, y + h - bl) if bl.positive?
+        line_to(x, y + tl)
+        curve_to(x, y + tl - (tl * KAPPA), x + tl - (tl * KAPPA), y, x + tl, y) if tl.positive?
         close
       end
 
@@ -68,6 +69,15 @@ module Stationery
         self
       end
 
+      def corner_radii(r, w, h)
+        return Array.new(4, [r, w / 2.0, h / 2.0].min) if r.is_a?(Numeric)
+
+        tl, tr, br, bl = r.map { |v| [v, 0].max }
+        scale = [[w, tl + tr], [w, bl + br], [h, tl + bl], [h, tr + br]]
+                .filter_map { |side, sum| side.fdiv(sum) if sum.positive? }.push(1).min
+        [tl, tr, br, bl].map { |v| v * scale }
+      end
+
       def point(x, y)
         x, y = apply(x, y) if @transform
         "#{@canvas.num(x)} #{@canvas.num(@canvas.page.height - y)}"

data/lib/stationery/canvas/text.rb

@@ -7,17 +7,21 @@ module Stationery
       BOLD_STROKE = 0.03
 
       # Draws `string` with its baseline at (x, y) in top-left coordinates and
-      # returns its advance width.
+      # returns its advance width. Standard ligatures form unless `ligatures:`
+      # is false or letter spacing is set.
       def text(string, x:, y:, font:, size:, color: "#000000", letter_spacing: 0, rise: 0, opacity: nil,
-               synthetic_bold: false, synthetic_oblique: false, underline: false, strikethrough: false)
+               synthetic_bold: false, synthetic_oblique: false, underline: false, strikethrough: false,
+               kerning: false, ligatures: true, word_spacing: 0)
         return 0 if string.empty?
 
         color = Color.parse(color)
-        width = font.width_of(string, size, letter_spacing:)
+        run = font.glyph_run(string, kerning:, ligatures: ligatures && letter_spacing.zero?)
+        run = run.with_word_spacing(word_spacing, size) unless word_spacing.zero?
+        width = run.width(size, letter_spacing:)
         graphics(opacity:) do |ops|
           ops << color.fill
           ops.push(color.stroke, "#{num(size * BOLD_STROKE)} w") if synthetic_bold
-          ops << text_object(string, x, y, font, size,
+          ops << text_object(run, x, y, font, size,
                              letter_spacing:, rise:, bold: synthetic_bold, oblique: synthetic_oblique)
         end
         decorate(x, y, width, font, size, color:, underline:, strikethrough:)
@@ -26,7 +30,7 @@ module Stationery
 
       private
 
-      def text_object(string, x, y, font, size, letter_spacing:, rise:, bold:, oblique:)
+      def text_object(run, x, y, font, size, letter_spacing:, rise:, bold:, oblique:)
         skew = oblique ? Fonts::Font::OBLIQUE_SKEW : 0
         ops = ["BT", "/#{@page.use(:Font, @resources.font(font))} #{num(size)} Tf"]
         ops << "#{num(letter_spacing)} Tc" unless letter_spacing.zero?
@@ -39,7 +43,7 @@ module Stationery
                else
                  "1 0 #{num(skew)} 1 #{num(x)} #{num(@page.height - y)} Tm"
                end
-        ops << "<#{font.encode(string).unpack1("H*").upcase}> Tj"
+        ops << run.to_operator
         ops << "ET"
         ops.join("\n")
       end

data/lib/stationery/canvas.rb

@@ -6,15 +6,19 @@ module Stationery
   # settings never leak into the next one.
   class Canvas
     include Text
+    include Debug
 
     CAPS = { butt: 0, round: 1, square: 2 }.freeze
     JOINS = { miter: 0, round: 1, bevel: 2 }.freeze
 
     attr_reader :page
 
-    def initialize(page, resources)
+    # `template: true` records anchors apart, for canvases page templates draw on.
+    def initialize(page, resources, template: false, debug: false)
       @page = page
       @resources = resources
+      @template = template
+      @debug = debug
     end
 
     def save
@@ -34,8 +38,8 @@ module Stationery
       shape(fill: color, opacity:) { |p| p.rect(x, y, w, h) }
     end
 
-    def rounded_rect(x, y, w, h, radius:, fill: nil, stroke: nil, line_width: 1, opacity: nil)
-      shape(fill:, stroke:, line_width:, opacity:) { |p| p.rounded_rect(x, y, w, h, radius) }
+    def rounded_rect(x, y, w, h, radius:, fill: nil, stroke: nil, line_width: 1, dash: nil, opacity: nil)
+      shape(fill:, stroke:, line_width:, dash:, opacity:) { |p| p.rounded_rect(x, y, w, h, radius) }
     end
 
     def circle(cx, cy, r, fill: nil, stroke: nil, line_width: 1, opacity: nil)
@@ -54,6 +58,19 @@ module Stationery
       shape(fill:, stroke:, line_width:, cap:, join:, dash:, even_odd:, opacity:, transform:, &)
     end
 
+    # Paints `shading` inside the path the block traces. `matrix` maps the
+    # shading's coordinates into top-left page space.
+    def shade(shading, matrix:, transform: nil, even_odd: false, opacity: nil)
+      path = Path.new(self, transform:)
+      yield path
+      name = @page.use(:Shading, @resources.shading(shading))
+      a, b, c, d, e, f = matrix
+      graphics(opacity:) do |ops|
+        ops << path.to_s << (even_odd ? "W* n" : "W n")
+        ops << "#{[a, -b, c, -d, e, @page.height - f].map { |v| num(v) }.join(" ")} cm" << "/#{name} sh"
+      end
+    end
+
     def image(image, x:, y:, width:, height:, opacity: nil)
       name = @page.use(:XObject, @resources.image(image))
       graphics(opacity:) do |ops|
@@ -62,11 +79,24 @@ module Stationery
       end
     end
 
-    # A clickable area opening `url`. Annotation rectangles live in absolute,
-    # untransformed page space, so they ignore clips and path transforms.
-    def link(x, y, w, h, url)
-      @page.annotations << { rect: [x, @page.height - y - h, x + w, @page.height - y].map { |v| num_value(v) },
-                             url: url.to_s }
+    # A clickable area opening `target`: a URL, or `#name` for an anchor in
+    # this document. Annotation rectangles live in absolute, untransformed
+    # page space, so they ignore clips and path transforms.
+    def link(x, y, w, h, target)
+      target = target.to_s
+      rect = [x, @page.height - y - h, x + w, @page.height - y].map { |v| num_value(v) }
+      @page.annotations << (target.start_with?("#") ? { rect:, dest: target[1..] } : { rect:, url: target })
+    end
+
+    # Names the point `y` on this page as a link target.
+    def anchor(name, y)
+      (@template ? @page.template_anchors : @page.anchors) << [name.to_s, num_value(@page.height - y)]
+    end
+
+    # Leaves room for the page number `anchor` lands on; Structure fills it in
+    # and adds the `link:` area ([x, y, w, h]) when the anchor exists.
+    def number_slot(anchor, x:, baseline:, width:, style:, link: nil)
+      @page.slots << Page::Slot.new(anchor.to_s, x, baseline, width, style, link)
     end
 
     def num(value) = PDF::Serializer.number(num_value(value))

data/lib/stationery/cli/fonts.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Stationery
+  class CLI
+    # `stationery fonts list` and `stationery fonts install PACK...`: copies
+    # pinned, SHA-256-checked font packs into vendor/fonts/<pack>/.
+    class Fonts
+      SUMMARY = "List or install font packs (Noto, Liberation, Inter) into vendor/fonts"
+      RESERVED_NAME_NOTE = 'Liberation fonts carry the Reserved Font Name "Liberation": copying them unmodified ' \
+                           "is fine; a modified copy must be renamed."
+
+      def initialize(out:, err:)
+        @out = out
+        @err = err
+        @options = { into: Stationery::Fonts::DEFAULT_DIR, force: false, from: nil }
+      end
+
+      def run(argv)
+        parser.parse!(argv)
+        return OK if @options.delete(:help)
+
+        case argv.shift
+        when "list" then list
+        when "install"
+          raise OptionParser::MissingArgument, "PACK" if argv.empty?
+
+          install(argv)
+        else usage
+        end
+      rescue OptionParser::ParseError => e
+        @err.puts "stationery fonts: #{e.message}"
+        usage
+      rescue Stationery::Error => e
+        raise Error, e.message
+      end
+
+      private
+
+      def parser
+        @parser ||= OptionParser.new do |opts|
+          opts.banner = "Usage: stationery fonts list [--into DIR]\n       " \
+                        "stationery fonts install PACK... [--into DIR] [--force] [--from PATH]"
+          opts.on("--into DIR", "Where packs live (default: #{Stationery::Fonts::DEFAULT_DIR})") do |dir|
+            @options[:into] = dir
+          end
+          opts.on("--force", "Replace files that are already installed") { @options[:force] = true }
+          opts.on("--from PATH", "Install offline from a directory or .tar.gz holding the files") do |path|
+            @options[:from] = path
+          end
+          opts.on("-h", "--help", "Show this help") do
+            @out.puts opts
+            @options[:help] = true
+          end
+        end
+      end
+
+      def usage
+        @err.puts parser
+        USAGE
+      end
+
+      def list
+        rows = Stationery::Fonts.catalog.map do |pack|
+          installed = File.file?(Stationery::Fonts.paths(pack.key, dir: @options[:into]).fetch(:regular))
+          [pack.key.to_s, pack.family, pack.license, installed ? "installed" : "-"]
+        end
+        widths = rows.transpose.map { |column| column.map(&:size).max }
+        rows.each { |row| @out.puts row.zip(widths).map { |cell, width| cell.ljust(width) }.join("  ").rstrip }
+        @out.puts "", RESERVED_NAME_NOTE
+        OK
+      end
+
+      def install(keys)
+        installer = Stationery::Fonts::Installer.new(**@options, out: @out)
+        keys.each do |key|
+          installer.install(key)
+          @out.puts "", "Use it with:", *Stationery::Fonts.usage(key, @options[:into]).map { "  #{it}" }
+        end
+        OK
+      end
+    end
+
+    register "fonts", Fonts
+  end
+end

data/lib/stationery/cli/render.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module Stationery
+  class CLI
+    # `stationery render FILE`: loads a Ruby file, finds the Document it
+    # defines and writes its PDF. A document whose constructor needs
+    # arguments renders from `def self.preview` returning an instance.
+    class Render
+      SUMMARY = "Render the Stationery::Document defined in a Ruby file to PDF"
+
+      def initialize(out:, err:)
+        @out = out
+        @err = err
+        @options = {}
+      end
+
+      def run(argv)
+        parser.parse!(argv)
+        return OK if @options[:help]
+
+        file = argv.shift or raise OptionParser::MissingArgument, "FILE"
+        render(file)
+      rescue OptionParser::ParseError => e
+        @err.puts "stationery render: #{e.message}", parser
+        USAGE
+      end
+
+      private
+
+      def parser
+        @parser ||= OptionParser.new do |opts|
+          opts.banner = "Usage: stationery render FILE [options]"
+          opts.on("-o", "--out PATH", "Where to write the PDF (default: FILE.pdf); - writes to stdout") do |path|
+            @options[:out] = path
+          end
+          opts.on("-c", "--class NAME", "The document class to render when FILE defines several") do |name|
+            @options[:class] = name
+          end
+          opts.on("--strict", "Fail without writing when layout reports warnings") { @options[:strict] = true }
+          opts.on("--debug", "Render with debug: true when the document supports it") { @options[:debug] = true }
+          opts.on("-h", "--help", "Show this help") do
+            @out.puts opts
+            @options[:help] = true
+          end
+        end
+      end
+
+      def render(file)
+        path = File.expand_path(file)
+        raise Error, "no such file: #{file}" unless File.file?(path)
+
+        document = instantiate(pick(load_documents(path), path))
+        pdf = to_pdf(document)
+        return FAILURE unless warnings_ok?(document)
+
+        write(pdf, @options[:out] || File.join(File.dirname(path), "#{File.basename(path, ".*")}.pdf"))
+        OK
+      end
+
+      # Documents that are new after loading FILE or whose view_template lives
+      # in it (so a file already loaded by the host still resolves).
+      def load_documents(path)
+        before = descendants(Document)
+        load(path)
+        after = descendants(Document)
+        (after - before) | after.select { |klass| template_file(klass) == path }
+      end
+
+      def pick(candidates, path)
+        return named_class if @options[:class]
+
+        candidates = candidates.reject { |klass| template_file(klass).nil? }
+        raise Error, "no Stationery::Document defined in #{path}" if candidates.empty?
+        return candidates.first if candidates.one?
+
+        names = candidates.map(&:name).sort.join(", ")
+        raise Error, "several documents defined in #{path} (#{names}); choose one with --class NAME"
+      end
+
+      def named_class
+        klass = Object.const_get(@options[:class])
+        raise Error, "#{klass} is not a Stationery::Document" unless klass.is_a?(Class) && klass < Document
+
+        klass
+      rescue NameError => e
+        raise Error, e.message
+      end
+
+      def instantiate(klass)
+        return klass.preview if klass.respond_to?(:preview)
+
+        begin
+          klass.new
+        rescue ArgumentError
+          raise Error, "#{klass} needs arguments; define `def self.preview` returning an instance to render"
+        end
+      end
+
+      def to_pdf(document)
+        return document.to_pdf unless @options[:debug]
+        return document.to_pdf(debug: true) if document.method(:to_pdf).parameters.include?(%i[key debug])
+
+        @err.puts "note: --debug is not supported by this version of Stationery; rendering without it"
+        document.to_pdf
+      end
+
+      def warnings_ok?(document)
+        warnings = Array(document.warnings)
+        warnings.each { |warning| @err.puts "warning: #{warning.message}" }
+        return true unless @options[:strict] && warnings.any?
+
+        @err.puts "stationery render: #{warnings.size} warning(s) under --strict; nothing written"
+        false
+      end
+
+      def write(pdf, target)
+        if target == "-"
+          @out.binmode
+          @out.write(pdf)
+        else
+          File.binwrite(target, pdf)
+          pages = pdf.scan(%r{/Type /Page\b}).size
+          @out.puts "wrote #{target} (#{pages} #{pages == 1 ? "page" : "pages"}, #{pdf.bytesize} bytes)"
+        end
+      end
+
+      def descendants(klass) = klass.subclasses.flat_map { |sub| [sub, *descendants(sub)] }
+
+      def template_file(klass)
+        method = klass.instance_method(:view_template)
+        method.source_location&.first unless method.owner == Component
+      end
+    end
+
+    register "render", Render
+  end
+end

data/lib/stationery/cli.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "stationery"
+
+module Stationery
+  # The `stationery` executable. Commands register themselves by name:
+  #
+  #   Stationery::CLI.register("render", Stationery::CLI::Render)
+  #
+  # A command is a class built with `new(out:, err:)` whose `#run(argv)`
+  # returns an exit code and that has a one-line `SUMMARY`.
+  class CLI
+    OK = 0
+    FAILURE = 1
+    USAGE = 2
+
+    # Raised by a command to fail with a message and exit code 1.
+    class Error < StandardError; end
+
+    class << self
+      def commands = @commands ||= {}
+
+      def register(name, command)
+        commands[name.to_s] = command
+      end
+
+      def start(argv, out: $stdout, err: $stderr) = new(out:, err:).run(argv.dup)
+    end
+
+    def initialize(out:, err:)
+      @out = out
+      @err = err
+    end
+
+    def run(argv)
+      case (name = argv.shift)
+      when nil then usage(@err, USAGE)
+      when "help", "--help", "-h" then usage(@out, OK)
+      when "--version", "-v" then version
+      else dispatch(name, argv)
+      end
+    end
+
+    private
+
+    def dispatch(name, argv)
+      command = self.class.commands.fetch(name) do
+        @err.puts "stationery: unknown command #{name.inspect}"
+        return usage(@err, USAGE)
+      end
+      command.new(out: @out, err: @err).run(argv)
+    rescue Error => e
+      @err.puts "stationery: #{e.message}"
+      FAILURE
+    end
+
+    def version
+      @out.puts VERSION
+      OK
+    end
+
+    def usage(io, code)
+      io.puts "Usage: stationery COMMAND [options]", "", "Commands:"
+      width = self.class.commands.keys.map(&:size).max.to_i
+      self.class.commands.each { |name, command| io.puts "  #{name.ljust(width)}  #{command::SUMMARY}" }
+      io.puts "", "Run `stationery COMMAND --help` for a command's options; `stationery --version` for the version."
+      code
+    end
+  end
+end
+
+require_relative "cli/render"
+require_relative "cli/fonts"