stationery 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7df6bdee0612f0952d1fb587f64720fb78d976e77b7327292dd261b5afbe14d7
+  data.tar.gz: 9c9c800f4c4a5aea772df63676eeb5936a3282828eec401494256d1691cae30b
+SHA512:
+  metadata.gz: ea8fa33394b8f68a0316d0bba056e97d48bee53db8ffd4b8addb9aea023b0d492f42c34884408d0771c136993bcc1249eb2064bfbe0f11cecb00aa52bc1561e0
+  data.tar.gz: dc14973b6ca838dd0be5651dc0cb51b404e8c0e3fe5958ad1edcac3dad9026ad6a66a13c21d15bb01483412a651a9aafad655c047d9c73868405d123608d1daa

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.1.0 (unreleased)
+
+- PDF writer with Flate streams, per-page resources and link annotations.
+- TrueType fonts: cmap 4/12, glyph subsetting, Type0/CIDFontType2 embedding with ToUnicode, synthetic bold and oblique.
+- JPEG and PNG images, including alpha soft masks and palette transparency.
+- Canvas: rectangles, rounded rectangles, circles, lines, Bézier paths, clipping, opacity, text runs, images, links.
+- Text: inline markup, Ruby run builder, wrapping, alignment, leading, truncate and shrink-to-fit.
+- Layout: flow, box, row/column, table, image, rule, spacer, page break, group, canvas escape hatch; pagination with header rows, keep-together and keep-with-next.
+- Components with Phlex's lifecycle; documents with page settings, font families, default text, metadata and page templates.
+- `Stationery::Rails#send_pdf`.

data/LICENSE.txt

@@ -0,0 +1,28 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Mikael Henriksson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+---
+
+Portions of lib/stationery/pdf, lib/stationery/fonts and lib/stationery/images
+are derived from the PDF engine of the receipts gem
+(https://github.com/excid3/receipts), MIT License,
+Copyright (c) 2020 Chris Oliver.

data/README.md

@@ -0,0 +1,145 @@
+# Stationery
+
+Pure-Ruby PDF documents built from Phlex-style components. Describe the page
+with rows, columns, boxes, tables, text and images; a box-layout engine
+measures, places and paginates them; a small PDF writer embeds subsetted
+TrueType fonts and JPEG/PNG images.
+
+- **No runtime dependencies.** Standard library only.
+- **No native extensions and no other processes.** No Prawn, no headless
+  Chrome, nothing to leak or kill.
+- **Declarative layout.** No cursor arithmetic: padding, backgrounds, borders,
+  radii, column widths and page breaks are the engine's job.
+
+```ruby
+gem "stationery"
+```
+
+Ruby 3.4 or newer.
+
+## A document
+
+```ruby
+class InvoicePdf < Stationery::Document
+  page size: :a4, margin: [40, 44, 56, 44]
+  font_family "Inter", regular: "fonts/Inter-Regular.ttf", bold: "fonts/Inter-Bold.ttf"
+  default_text font: "Inter", size: 9, color: "#1F2937"
+  metadata title: "Invoice"
+
+  page_template do |page|
+    box(at: [44, page.height - 34], width: page.content_box.width) do
+      text "Page #{page.number} of #{page.count}", size: 7, align: :right
+    end
+  end
+
+  def initialize(invoice)
+    super()
+    @invoice = invoice
+  end
+
+  def view_template
+    row(align: :middle) do
+      column(width: 0.5) { text "Invoice #{@invoice.number}", size: 22, weight: :bold }
+      column(width: 0.5, align: :right) { image "logo.png", height: 34, align: :right }
+    end
+    rule height: 3, color: "#4F46E5"
+    spacer 18
+    box(background: "#F3F4F6", radius: 6, padding: 12, width: 190) do
+      text "AMOUNT DUE", size: 8, weight: :bold, letter_spacing: 0.5
+      text @invoice.total, size: 19, weight: :bold, color: "#4F46E5"
+    end
+    table(@invoice.rows, width: :full, widths: [nil, 45, 80, 85], header: true, cell: { borders: [] }) do |t|
+      t.row(0).set(background: "#4F46E5", color: "#FFFFFF", weight: :bold)
+      t.columns(1..).align = :right
+      t.zebra(from: 2, color: "#F9FAFB")
+    end
+  end
+end
+
+InvoicePdf.new(invoice).to_pdf          # => "%PDF-1.7…" (binary String)
+InvoicePdf.new(invoice).to_pdf("a.pdf") # also writes a path or an IO
+```
+
+`examples/invoice.rb` is a complete, runnable invoice: `ruby -Ilib examples/invoice.rb`.
+
+## Elements
+
+| Element | What it does |
+|---|---|
+| `text(string, **style)` | A paragraph. Plain strings are literal. |
+| `text(string, markup: true)` | Reads `<b> <i> <u> <strikethrough> <sub> <sup> <br> <color rgb=""> <font size="" name=""> <link href="">`. |
+| `text { b "Total"; plain " due" }` | Styled runs in Ruby. Take a block argument (`{ \|t\| t.b @x }`) to keep your own `self`. |
+| `box(padding:, background:, border:, radius:, width:, height:, overflow:, at:) { }` | A container. Moves to the next page whole. `overflow: :truncate` or `:shrink_to_fit` for fixed heights. `at: [x, y]` pins it to a page position. |
+| `row(gap:, align:) { column(width:) { } }` | Columns side by side. `width:` is points, a fraction (`0.5`), `:auto` or `nil` (equal share). |
+| `table(rows, widths:, width:, header:, cell:) { \|t\| }` | Tables. Style with `t.row(0)`, `t.rows(-1)`, `t.column(1)`, `t.columns(1..)`, chained, plus `t.zebra`. Header rows repeat after a page break. |
+| `image(path_or_io, width:, height:, fit:, align:)` | JPEG or PNG, aspect preserved. |
+| `rule(height:, color:)`, `spacer(height)`, `page_break` | Dividers and spacing. |
+| `group(keep_together: true) { }` | Keep a block on one page. |
+| `text_style(**style) { }` | Default text style for a block. |
+| `canvas(height:) { \|canvas, rect\| }` | Draw directly: rectangles, rounded rectangles, circles, lines, Bézier paths, clipping, images, links. |
+
+Text style options: `font`, `size`, `weight` (`:regular`, `:bold`), `style` (`:italic`), `color`,
+`letter_spacing`, `underline`, `strikethrough`, `link`, `opacity`, `align`, `leading`.
+Colours are `"#RRGGBB"`, `"RRGGBB"`, `"#RGB"`, `[r, g, b]` (0-255) or `[c, m, y, k]` (0-100).
+
+## Components
+
+Components have Phlex's lifecycle (`around_template`, `before_template`,
+`view_template`, `after_template`) and `render`:
+
+```ruby
+class Callout < Stationery::Component
+  def initialize(color:) = (super(); @color = color)
+  def view_template(&) = box(background: @color, padding: 12, radius: 6, &)
+end
+
+render Callout.new(color: "#F3F4F6") { text "Amount due" }
+```
+
+`render` takes a component, a component class, a string, a proc or a list of those.
+
+## Pages
+
+- `page size: :a4 | :a3 | :a5 | :letter | :legal | :tabloid | [w, h], margin:, layout: :landscape`
+- `page_template { |page| … }` runs on every page after pagination with `page.number`, `page.count`,
+  `page.width`, `page.height`, `page.margin` and `page.content_box`. `page_template(layer: :background)`
+  paints under the content (full-bleed backgrounds).
+- Content taller than a page is placed anyway; `document.warnings` lists every overflow.
+
+## Rails
+
+```ruby
+require "stationery/rails" # adds send_pdf to controllers
+
+def show = send_pdf(InvoicePdf.new(@invoice), filename: "invoice.pdf")
+```
+
+## Fonts and images
+
+Fonts are TrueType (`.ttf`) files. Only the glyphs a document uses are
+embedded, with a ToUnicode map so text copies and searches correctly. A style
+without its own file (bold, italic) is synthesised. There is no built-in
+font: declare at least one `font_family`.
+
+Images are JPEG (grey, RGB, CMYK) and PNG (every colour type, alpha as a soft
+mask). Parsed fonts and images are cached per process.
+
+## Why not Prawn, Chrome or Typst?
+
+- **Prawn** is an imperative cursor API: every document does its own layout
+  arithmetic. Stationery is a layout engine with a component DSL.
+- **Headless Chrome** (Grover, ferrum_pdf) renders HTML beautifully but runs
+  a browser per worker; stray processes and memory are the price.
+- **Typst** is excellent but a native extension and a second template language.
+
+## Limitations
+
+No kerning or ligatures, no OpenType/CFF, TrueType collections, variable
+fonts or WOFF; no full justification; no SVG (paths are available on the
+canvas); no encryption, outlines, forms or tagged PDF; boxes and rows do not
+split across pages.
+
+## License
+
+MIT. The PDF writer, TrueType subsetter and image decoders are derived from
+the [receipts](https://github.com/excid3/receipts) gem (MIT).

data/lib/stationery/builder.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+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
+
+    # Collects a row's columns; anything that is not already a column box is
+    # wrapped in one.
+    class Columns
+      attr_reader :nodes
+
+      def initialize = @nodes = []
+
+      def <<(node)
+        @nodes << (node.is_a?(Layout::Box) ? node : Layout::Box.new(Layout::Flow.new([node])))
+        self
+      end
+    end
+
+    attr_reader :root, :book
+
+    def initialize(book:, text: {})
+      @book = book
+      @root = Layout::Flow.new
+      @containers = [@root]
+      @text = [text]
+    end
+
+    def add(node)
+      @containers.last << node
+      node
+    end
+
+    def within(container)
+      @containers << container
+      yield
+      container
+    ensure
+      @containers.pop
+    end
+
+    def with_text(**overrides)
+      @text << text_defaults.merge(overrides.compact)
+      yield
+    ensure
+      @text.pop
+    end
+
+    def text_defaults = @text.last
+
+    def style(options = {})
+      options = text_defaults.merge(options)
+      family = options[:font] || @book.families.keys.first || "default"
+      Text::Style.new(family: family.to_s, **options.slice(*STYLE_KEYS))
+    end
+
+    def context(style = self.style) = Layout::Context.new(book: @book, style:)
+  end
+end

data/lib/stationery/canvas/path.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Stationery
+  class Canvas
+    # Collects path segments in top-left coordinates and writes them in PDF
+    # space. An optional affine transform (a, b, c, d, e, f), also in top-left
+    # space, is applied to every point — how scaled icons are drawn.
+    class Path
+      KAPPA = 0.5522847498
+
+      def initialize(canvas, transform: nil)
+        @canvas = canvas
+        @transform = transform
+        @ops = []
+      end
+
+      def move_to(x, y) = add("#{point(x, y)} m")
+      def line_to(x, y) = add("#{point(x, y)} l")
+      def curve_to(x1, y1, x2, y2, x, y) = add("#{point(x1, y1)} #{point(x2, y2)} #{point(x, y)} c")
+      def close = add("h")
+
+      def rect(x, y, w, h)
+        unless @transform
+          return add([x, @canvas.page.height - y - h, w, h].map { |v| @canvas.num(v) }.push("re").join(" "))
+        end
+
+        move_to(x, y)
+        line_to(x + w, y)
+        line_to(x + w, y + h)
+        line_to(x, y + h)
+        close
+      end
+
+      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
+
+        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)
+        close
+      end
+
+      def ellipse(cx, cy, rx, ry)
+        kx = rx * KAPPA
+        ky = ry * KAPPA
+        move_to(cx + rx, cy)
+        curve_to(cx + rx, cy + ky, cx + kx, cy + ry, cx, cy + ry)
+        curve_to(cx - kx, cy + ry, cx - rx, cy + ky, cx - rx, cy)
+        curve_to(cx - rx, cy - ky, cx - kx, cy - ry, cx, cy - ry)
+        curve_to(cx + kx, cy - ry, cx + rx, cy - ky, cx + rx, cy)
+        close
+      end
+
+      def to_s = @ops.join("\n")
+
+      private
+
+      def add(op)
+        @ops << op
+        self
+      end
+
+      def point(x, y)
+        x, y = apply(x, y) if @transform
+        "#{@canvas.num(x)} #{@canvas.num(@canvas.page.height - y)}"
+      end
+
+      def apply(x, y)
+        a, b, c, d, e, f = @transform
+        [(a * x) + (c * y) + e, (b * x) + (d * y) + f]
+      end
+    end
+  end
+end

data/lib/stationery/canvas/text.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Stationery
+  class Canvas
+    # Single-run text drawing: one font, size and colour at a baseline.
+    module Text
+      BOLD_STROKE = 0.03
+
+      # Draws `string` with its baseline at (x, y) in top-left coordinates and
+      # returns its advance width.
+      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)
+        return 0 if string.empty?
+
+        color = Color.parse(color)
+        width = font.width_of(string, 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,
+                             letter_spacing:, rise:, bold: synthetic_bold, oblique: synthetic_oblique)
+        end
+        decorate(x, y, width, font, size, color:, underline:, strikethrough:)
+        width
+      end
+
+      private
+
+      def text_object(string, 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?
+        ops << "#{num(rise)} Ts" unless rise.zero?
+        ops << "2 Tr" if bold
+        # Td from the identity text matrix is an absolute position (and what
+        # text-extraction tools read positions from); Tm only when shearing.
+        ops << if skew.zero?
+                 "#{num(x)} #{num(@page.height - y)} Td"
+               else
+                 "1 0 #{num(skew)} 1 #{num(x)} #{num(@page.height - y)} Tm"
+               end
+        ops << "<#{font.encode(string).unpack1("H*").upcase}> Tj"
+        ops << "ET"
+        ops.join("\n")
+      end
+
+      def decorate(x, y, width, font, size, color:, underline:, strikethrough:)
+        fill_rect(x, y - font.underline_position(size), width, font.underline_thickness(size), color:) if underline
+        return unless strikethrough
+
+        fill_rect(x, y - font.strikeout_position(size), width, font.strikeout_size(size), color:)
+      end
+    end
+  end
+end

data/lib/stationery/canvas.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Stationery
+  # Draws on one page in top-left coordinates (points, y grows downwards).
+  # Every operation is wrapped in its own graphics state so colours and line
+  # settings never leak into the next one.
+  class Canvas
+    include Text
+
+    CAPS = { butt: 0, round: 1, square: 2 }.freeze
+    JOINS = { miter: 0, round: 1, bevel: 2 }.freeze
+
+    attr_reader :page
+
+    def initialize(page, resources)
+      @page = page
+      @resources = resources
+    end
+
+    def save
+      emit("q")
+      yield self
+      emit("Q")
+    end
+
+    def clip(x, y, w, h, radius: 0)
+      save do
+        emit(Path.new(self).rounded_rect(x, y, w, h, radius).to_s, "W n")
+        yield self
+      end
+    end
+
+    def fill_rect(x, y, w, h, color:, opacity: nil)
+      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) }
+    end
+
+    def circle(cx, cy, r, fill: nil, stroke: nil, line_width: 1, opacity: nil)
+      shape(fill:, stroke:, line_width:, opacity:) { |p| p.ellipse(cx, cy, r, r) }
+    end
+
+    def line(x1, y1, x2, y2, color:, width: 1, dash: nil, cap: :butt, opacity: nil)
+      shape(stroke: color, line_width: width, dash:, cap:, opacity:) do |p|
+        p.move_to(x1, y1)
+        p.line_to(x2, y2)
+      end
+    end
+
+    def path(fill: nil, stroke: nil, line_width: 1, cap: :butt, join: :miter, dash: nil, even_odd: false,
+             opacity: nil, transform: nil, &)
+      shape(fill:, stroke:, line_width:, cap:, join:, dash:, even_odd:, opacity:, transform:, &)
+    end
+
+    def image(image, x:, y:, width:, height:, opacity: nil)
+      name = @page.use(:XObject, @resources.image(image))
+      graphics(opacity:) do |ops|
+        ops << "#{num(width)} 0 0 #{num(height)} #{num(x)} #{num(@page.height - y - height)} cm"
+        ops << "/#{name} Do"
+      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 }
+    end
+
+    def num(value) = PDF::Serializer.number(num_value(value))
+
+    private
+
+    def num_value(value)
+      value.is_a?(Float) && value == value.round ? value.round : value
+    end
+
+    def shape(fill: nil, stroke: nil, line_width: 1, cap: nil, join: nil, dash: nil, even_odd: false,
+              opacity: nil, transform: nil)
+      path = Path.new(self, transform:)
+      yield path
+      graphics(opacity:) do |ops|
+        ops << Color.parse(fill).fill if fill
+        ops << Color.parse(stroke).stroke if stroke
+        ops.concat(line_style(stroke, line_width, cap, join, dash))
+        ops << path.to_s << paint_operator(fill, stroke, even_odd)
+      end
+    end
+
+    def line_style(stroke, width, cap, join, dash)
+      return [] unless stroke
+
+      ops = ["#{num(width)} w"]
+      ops << "[#{dash.map { |v| num(v) }.join(" ")}] 0 d" if dash
+      ops << "#{CAPS.fetch(cap)} J" if cap && cap != :butt
+      ops << "#{JOINS.fetch(join)} j" if join && join != :miter
+      ops
+    end
+
+    def paint_operator(fill, stroke, even_odd)
+      if fill && stroke then even_odd ? "B*" : "B"
+      elsif fill then even_odd ? "f*" : "f"
+      elsif stroke then "S"
+      else "n"
+      end
+    end
+
+    def graphics(opacity: nil)
+      ops = []
+      ops << "/#{@page.use(:ExtGState, @resources.opacity(opacity))} gs" if opacity && opacity < 1
+      yield ops
+      emit("q", *ops, "Q")
+    end
+
+    def emit(*ops)
+      @page.content << ops.join("\n") << "\n"
+    end
+  end
+end

data/lib/stationery/color.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Stationery
+  # A device colour. Accepts "#RRGGBB", "RRGGBB", "#RGB", [r, g, b] in 0-255 or
+  # [c, m, y, k] in 0-100. Input values are never mutated.
+  class Color
+    HEX = /\A#?(\h{3}|\h{6})\z/
+
+    attr_reader :space, :components
+
+    def self.parse(value)
+      case value
+      when Color then value
+      when String then from_hex(value)
+      when Array then from_array(value)
+      else invalid(value)
+      end
+    end
+
+    def self.from_hex(value)
+      hex = value[HEX, 1] || invalid(value)
+      hex = hex.chars.map { |c| c * 2 }.join if hex.size == 3
+      new(:rgb, hex.scan(/../).map { |pair| pair.to_i(16) / 255.0 })
+    end
+
+    def self.from_array(value)
+      case value.size
+      when 3 then new(:rgb, value.map { |v| v.to_f / 255 })
+      when 4 then new(:cmyk, value.map { |v| v.to_f / 100 })
+      else invalid(value)
+      end
+    end
+
+    def self.invalid(value)
+      raise ArgumentError, "not a colour: #{value.inspect} (use \"#RRGGBB\", [r, g, b] or [c, m, y, k])"
+    end
+
+    def initialize(space, components)
+      @space = space
+      @components = components.freeze
+      freeze
+    end
+
+    def fill = operator(false)
+    def stroke = operator(true)
+
+    def ==(other)
+      other.is_a?(Color) && other.space == space && other.components == components
+    end
+    alias eql? ==
+
+    def hash = [space, components].hash
+
+    private
+
+    def operator(stroke)
+      numbers = components.map { |v| PDF::Serializer.number(v.round(4)) }.join(" ")
+      op = space == :rgb ? "rg" : "k"
+      "#{numbers} #{stroke ? op.upcase : op}"
+    end
+  end
+end

data/lib/stationery/component.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Stationery
+  # A reusable piece of a document, with Phlex's lifecycle:
+  #
+  #   class Callout < Stationery::Component
+  #     def initialize(color:) = @color = color
+  #     def view_template(&) = box(background: @color, padding: 12, radius: 6, &)
+  #   end
+  #
+  #   render Callout.new(color: "#F3F4F6") { text "Amount due" }
+  class Component
+    include Elements
+
+    def call(builder, &)
+      @_builder = builder
+      around_template do
+        before_template
+        view_template(&)
+        after_template
+      end
+      nil
+    end
+
+    def around_template = yield
+    def before_template = nil
+    def after_template = nil
+    def view_template(&) = yield_content(&)
+
+    def render(renderable, &)
+      case renderable
+      when Component then renderable.call(@_builder, &)
+      when Class then renderable < Component ? render(renderable.new, &) : cannot_render(renderable)
+      when String then text(renderable)
+      when Proc, Method then yield_content(&renderable)
+      when Enumerable then renderable.each { |item| render(item, &) }
+      else cannot_render(renderable)
+      end
+      nil
+    end
+
+    def yield_content(&block)
+      return unless block
+
+      block.arity.zero? ? yield : yield(self)
+    end
+
+    private
+
+    def cannot_render(renderable)
+      raise ArgumentError, "You can't render #{renderable.inspect}; render a component, class, string, proc or list."
+    end
+  end
+end