bandoola 0.1.0

data/lib/bandoola/view.rb

@@ -0,0 +1,364 @@
+require_relative "view/header"
+require_relative "view/file"
+require_relative "view/style"
+require_relative "view/element"
+require_relative "view/resources"
+
+module Bandoola
+  # A Phlex-style base class for declaring PDF documents.
+  #
+  # Subclass it and describe the document in #view_template using the element
+  # methods below (#div, #text). Each call builds a node in a tree; once the
+  # tree is complete #render lays it out — resolving widths, padding, margins
+  # and reflow (see Element) — and paints it into @buffer, which Header then
+  # wraps into a finished PDF stored in @contents. #write persists it.
+  #
+  # The supporting concerns live in their own files so this one stays focused
+  # on the tags: Style (the Tailwind-ish `class` vocabulary), Element and its
+  # subclasses (layout + paint), Header (PDF structure) and File (writing).
+  #
+  #   class Hello < Bandoola::View
+  #     def view_template
+  #       div(class: "p-4 w-1/2") do
+  #         text { "Hello World!" }
+  #       end
+  #     end
+  #   end
+  #
+  #   view = Hello.new
+  #   view.render
+  #   view.write("hello.pdf")
+  class View
+    # A4 proportions (1 : √2) at 96 DPI rather than the PDF default of 72, so
+    # the page is larger and the fixed-point text/spacing classes (text-xs,
+    # p-4, …) read smaller against it. Override #width/#height in a subclass
+    # for a different page.
+    PAGE_WIDTH = 794
+    PAGE_HEIGHT = 1123
+
+    # Printable margin around the page (1 inch at 96 DPI), plus text metrics:
+    # the default glyph height and the vertical step between lines.
+    MARGIN = 96
+    FONT_SIZE = 24
+    LINE_HEIGHT = 28
+
+    include Header
+    include Writer
+
+    # Every subclass, in the order it was defined. The CLI uses this to find
+    # the view a loaded file declares.
+    @registry = []
+
+    class << self
+      attr_reader :registry
+    end
+
+    def self.inherited(subclass)
+      super
+      View.registry << subclass
+    end
+
+    NORMAL_WEIGHT = 400
+    # Weights at or above this use a real bold face (a bold standard base font,
+    # or a registered bold file); lighter gaps are synthesised as faux bold.
+    BOLD_THRESHOLD = 700
+
+    # The three always-available families, with their regular and bold standard
+    # base fonts (the standard 14 PDF fonts ship a real bold for each).
+    BUILTIN_FONTS = {
+      "sans" => { NORMAL_WEIGHT => "Helvetica", BOLD_THRESHOLD => "Helvetica-Bold" },
+      "serif" => { NORMAL_WEIGHT => "Times-Roman", BOLD_THRESHOLD => "Times-Bold" },
+      "mono" => { NORMAL_WEIGHT => "Courier", BOLD_THRESHOLD => "Courier-Bold" }
+    }.freeze
+
+    # Register an embedded TrueType font for this view, usable via font-<name>.
+    # +source+ is either a single path (one regular face) or a Hash of weight
+    # => path for several files, since a .ttf holds only one weight:
+    #
+    #   register_font :cool, "./fonts/cool-font.ttf"
+    #   register_font :cool, regular: "./cool.ttf", bold: "./cool-bold.ttf"
+    def self.register_font(name, source)
+      font_faces_registry[name.to_s] = normalize_faces(source)
+    end
+
+    def self.font_faces_registry
+      @font_faces_registry ||= {}
+    end
+
+    # Whether embedded fonts are compacted (glyphs renumbered into a dense
+    # range — smaller files). On by default; opt out per view with
+    # `compact_fonts false` to trade a little size for a simpler subset.
+    # A positional boolean keeps the class-macro reading: `compact_fonts false`.
+    def self.compact_fonts(value = true) # rubocop:disable Style/OptionalBooleanParameter
+      @compact_fonts = value
+    end
+
+    def self.compact_fonts?
+      return @compact_fonts unless @compact_fonts.nil?
+
+      superclass.respond_to?(:compact_fonts?) ? superclass.compact_fonts? : true
+    end
+
+    # The registered weight => path faces for a family, walking up the class
+    # hierarchy so a subclass inherits its parent's registrations.
+    def self.font_faces(family)
+      klass = self
+      while klass.respond_to?(:font_faces_registry)
+        faces = klass.font_faces_registry[family]
+        return faces if faces
+
+        klass = klass.superclass
+      end
+      nil
+    end
+
+    # Normalize a register_font source to a weight(Integer) => path Hash.
+    def self.normalize_faces(source)
+      return { NORMAL_WEIGHT => source } unless source.is_a?(Hash)
+
+      source.to_h { |weight, path| [weight_value(weight), path] }
+    end
+
+    def self.weight_value(weight)
+      return weight if weight.is_a?(Integer)
+
+      key = weight.to_s
+      return NORMAL_WEIGHT if key == "regular"
+
+      Style::Typography::WEIGHTS.fetch(key) { raise Error, "unknown font weight: #{weight}" }
+    end
+
+    PAGE_BREAK_EPSILON = 0.01
+
+    # The inherited font/weight and a text measurer, threaded through layout so
+    # Text can wrap. #inherit applies a div's font classes to its children.
+    Typeset = Struct.new(:font, :weight, :measure) do
+      def inherit(style)
+        Typeset.new(style.font || font, style.font_weight || weight, measure)
+      end
+    end
+    # Used when a tree is laid out without typesetting (no wrapping).
+    PLAIN_TYPESET = Typeset.new("sans", NORMAL_WEIGHT, nil)
+
+    # contents: the rendered PDF bytes. page_number/page_count are set while a
+    # page's #header and #footer run, so those methods can show "Page 2 of 5".
+    attr_reader :contents, :page_number, :page_count
+
+    # Page geometry, in PDF points. Override any of these in a subclass to
+    # change the page — e.g. `def width = 1234` for a wider page.
+    def width = PAGE_WIDTH
+    def height = PAGE_HEIGHT
+    def margin = MARGIN
+
+    # Lay out the document and serialize it. The body (#view_template) flows into
+    # the area between the optional #header and #footer bands and splits across
+    # as many pages as it needs; the header and footer repeat on every page.
+    def render
+      @resources = Resources.new(method(:resolve_font))
+      @typeset = Typeset.new("sans", NORMAL_WEIGHT, method(:measure_text))
+
+      # Header/footer heights (their content is assumed not to change height
+      # between pages); the body gets what's left.
+      @page_number = @page_count = 1
+      header_height = band_height(:header)
+      footer_height = band_height(:footer)
+      body_top = (height - margin) - header_height
+      body_height = content_height - header_height - footer_height
+
+      # Lay the body out in one tall column, then split it into pages.
+      body = build_tree { view_template }
+      body.layout(margin, body_top, content_width, body_height, @typeset)
+      pages = paginate(body.children, body_height, body_top)
+
+      @page_buffers = pages.each_with_index.map do |children, index|
+        @page_number = index + 1
+        @page_count = pages.size
+        buffer = String.new(encoding: Encoding::ASCII_8BIT)
+        paint_header(buffer)
+        paint_footer(buffer)
+        children.each { |child| child.paint(buffer, @resources) }
+        buffer
+      end
+
+      @contents = serialize
+    end
+
+    # Resolve a (family, weight) to a face: [cache_key, Font, native_weight].
+    # The native weight lets the caller add faux bold for any remaining gap.
+    # sans/serif/mono are standard; other families must be registered.
+    def resolve_font(family, weight)
+      if BUILTIN_FONTS.key?(family)
+        standard_face(family, weight)
+      elsif (faces = self.class.font_faces(family))
+        embedded_face(faces, weight)
+      else
+        raise Error, "unknown font: font-#{family}"
+      end
+    end
+
+    # Subclasses describe their document here.
+    def view_template
+      raise NotImplementedError, "#{self.class} must implement #view_template"
+    end
+
+    # Image file extension to loader class.
+    LOADERS = { ".svg" => Svg, ".jpg" => Jpeg, ".jpeg" => Jpeg }.freeze
+
+    private
+
+    def content_width = width - (2 * margin)
+    def content_height = height - (2 * margin)
+
+    # Run a tag-defining method (view_template/header/footer) into a fresh tree.
+    def build_tree
+      root = Element.new(Style.none)
+      @stack = [root]
+      yield
+      root
+    end
+
+    # Width of +string+ at +size+ points in the resolved (family, weight) face.
+    # The text measurer threaded through layout so Text can wrap.
+    def measure_text(string, family, weight, size)
+      _key, face, = resolve_font(family, weight)
+      face.width_of(string, size)
+    end
+
+    # The laid-out height of the header/footer band (0 when not defined).
+    def band_height(name)
+      return 0.0 unless respond_to?(name)
+
+      tree = build_tree { send(name) }
+      tree.layout(margin, height - margin, content_width, height, @typeset)
+      tree.h
+    end
+
+    # Greedily pack top-level body elements into pages, then shift each page's
+    # elements up so the page starts at +body_top+. An element taller than a
+    # page is left to overflow (no splitting yet).
+    def paginate(children, body_height, body_top)
+      pages = pack_pages(children, body_height)
+      reposition(pages, body_top)
+      pages
+    end
+
+    def pack_pages(children, body_height)
+      pages = [[]]
+      used = 0.0
+      children.each do |child|
+        # The space a child takes is its height plus its own top/bottom margins,
+        # the same as the flow that laid it out — otherwise margined content
+        # overflows past the page (and onto the footer).
+        outer = child.style.margin.top + child.h + child.style.margin.bottom
+        if used.positive? && used + outer > body_height + PAGE_BREAK_EPSILON
+          pages << []
+          used = 0.0
+        end
+        pages.last << child
+        used += outer
+      end
+      pages
+    end
+
+    def reposition(pages, body_top)
+      pages.each do |group|
+        next if group.empty?
+
+        delta = body_top - group.first.top
+        group.each { |child| child.offset(delta) } unless delta.zero?
+      end
+    end
+
+    def paint_header(buffer)
+      return unless respond_to?(:header)
+
+      tree = build_tree { header }
+      tree.layout(margin, height - margin, content_width, height, @typeset)
+      tree.paint(buffer, @resources)
+    end
+
+    def paint_footer(buffer)
+      return unless respond_to?(:footer)
+
+      tree = build_tree { footer }
+      tree.layout(margin, height - margin, content_width, height, @typeset) # measure its height
+      tree.layout(margin, margin + tree.h, content_width, height, @typeset) # sit it above the bottom margin
+      tree.paint(buffer, @resources)
+    end
+
+    # Load (and cache) the image at +src+ so a logo repeated across pages embeds
+    # once and rebuilt header/footer trees reuse it.
+    def image_for(src)
+      image_cache[src] ||= begin
+        loader = LOADERS[File.extname(src).downcase]
+        raise Error, "unsupported image type: #{src}" unless loader
+
+        loader.load(src)
+      end
+    end
+
+    def image_cache
+      @image_cache ||= {}
+    end
+
+    def font_cache
+      @font_cache ||= {}
+    end
+
+    # A built-in family: a real bold base font at/above the bold threshold,
+    # otherwise the regular base. Its native weight is bold or normal exactly.
+    def standard_face(family, weight)
+      bold = weight >= BOLD_THRESHOLD
+      native = bold ? BOLD_THRESHOLD : NORMAL_WEIGHT
+      base = BUILTIN_FONTS.fetch(family).fetch(native)
+      [base, (font_cache[base] ||= StandardFont.new(base)), native]
+    end
+
+    # A registered family: the heaviest available face no heavier than the
+    # requested weight (or the lightest if all are heavier).
+    def embedded_face(faces, weight)
+      native = pick_weight(faces.keys, weight)
+      path = faces.fetch(native)
+      font = (font_cache[path] ||= EmbeddedFont.load(path, compact: self.class.compact_fonts?))
+      [path, font, native]
+    end
+
+    def pick_weight(available, requested)
+      available.select { |candidate| candidate <= requested }.max || available.min
+    end
+
+    # The div element: a rectangle that contains other elements. The block
+    # nests further elements inside it. The +class+ keyword accepts a String
+    # of space-separated tokens or an Array of tokens (see Style).
+    def div(**attributes, &)
+      append(Div.new(Style.parse(attributes[:class])), &)
+    end
+
+    # The text element. The block returns the string to render; embedded
+    # newlines become separate lines.
+    def text(**attributes)
+      content = block_given? ? yield.to_s : ""
+      @stack.last.children << Text.new(Style.parse(attributes[:class]), content)
+      nil
+    end
+
+    # The image element. +src+ is a path to an SVG or JPEG. Sizing follows the
+    # width/height classes (see Style); with none it uses the image's own size.
+    def img(src:, **attributes)
+      @stack.last.children << Img.new(Style.parse(attributes[:class]), image_for(src))
+      nil
+    end
+
+    # Add +element+ to the current parent, and — if a block is given — make
+    # it the parent while the block runs so nested tags land inside it.
+    def append(element, &block)
+      @stack.last.children << element
+      return element unless block
+
+      @stack.push(element)
+      yield
+      @stack.pop
+      nil
+    end
+  end
+end

data/lib/bandoola.rb

@@ -0,0 +1,14 @@
+require_relative "bandoola/version"
+
+module Bandoola
+  class Error < StandardError; end
+end
+
+require_relative "bandoola/svg"
+require_relative "bandoola/jpeg"
+require_relative "bandoola/true_type_font"
+require_relative "bandoola/true_type_subset"
+require_relative "bandoola/font"
+require_relative "bandoola/standard_metrics"
+require_relative "bandoola/view"
+require_relative "bandoola/cli"

data/sig/bandoola.rbs

@@ -0,0 +1,4 @@
+module Bandoola
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification
+name: bandoola
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Johan Halse
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Bandoola builds PDF documents from plain Ruby, styling elements with
+  a Tailwind-inspired class vocabulary. No runtime dependencies.
+email:
+- johan@hal.se
+executables:
+- bandoola
+extensions: []
+extra_rdoc_files: []
+files:
+- ".tool-versions"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- exe/bandoola
+- lib/bandoola.rb
+- lib/bandoola/cli.rb
+- lib/bandoola/font.rb
+- lib/bandoola/jpeg.rb
+- lib/bandoola/standard_metrics.rb
+- lib/bandoola/svg.rb
+- lib/bandoola/true_type_font.rb
+- lib/bandoola/true_type_subset.rb
+- lib/bandoola/version.rb
+- lib/bandoola/view.rb
+- lib/bandoola/view/element.rb
+- lib/bandoola/view/file.rb
+- lib/bandoola/view/header.rb
+- lib/bandoola/view/resources.rb
+- lib/bandoola/view/style.rb
+- lib/bandoola/view/style/borders.rb
+- lib/bandoola/view/style/colors.rb
+- lib/bandoola/view/style/spacing.rb
+- lib/bandoola/view/style/typography.rb
+- sig/bandoola.rbs
+homepage: https://github.com/johanhalse/bandoola
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://gem.coop
+  homepage_uri: https://github.com/johanhalse/bandoola
+  source_code_uri: https://github.com/johanhalse/bandoola
+  changelog_uri: https://github.com/johanhalse/bandoola/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 4.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.15
+specification_version: 4
+summary: A small, dependency-free PDF generator for Ruby with Tailwind-style classes.
+test_files: []