stationery 0.11.0 → 0.12.0

data/examples/flyer.rb

@@ -0,0 +1,336 @@
+# frozen_string_literal: true
+
+# An A4 event flyer: a cover photo bled to the page edges, a date pill, a
+# stats band, prose from HTML, a tilted photo collage, a price table,
+# accommodation cards, a gallery grid, testimonials and a call to action with
+# a link. Run it to write examples/flyer.pdf:
+#
+#   ruby -Ilib examples/flyer.rb
+#   ruby -Ilib exe/stationery render examples/flyer.rb
+require "stationery"
+
+class ExampleFlyer < Stationery::Document
+  ASSETS = File.expand_path("assets", __dir__)
+  PAGE = "#FAF8F2"
+  BAND = "#F1EEE7"
+  HAIRLINE = "#E3DDD3"
+  PRIMARY = "#345644"
+  PRIMARY_CONTENT = "#F3FBF6"
+  ACCENT = "#C1983A"
+  INK = "#3A2A20"
+  MUTED = "#74685F"
+  FAINT = "#9A9189"
+  TINT = "#E6E8E1"
+  MARGIN = 48
+  COVER_HEIGHT = 220
+  OVERHANG = 24
+
+  SVG_OPEN = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" ' \
+             'stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round">'
+  ICONS = {
+    calendar: '<path d="M4 6h16v14H4z M4 10h16 M8 3v4 M16 3v4"/>',
+    pin: '<path d="M12 21s-6-5.5-6-11a6 6 0 0 1 12 0c0 5.5-6 11-6 11z"/><circle cx="12" cy="10" r="2.2"/>',
+    users: '<circle cx="9" cy="8" r="3.2"/>' \
+           '<path d="M3 20a6 6 0 0 1 12 0 M15.5 5.5a3 3 0 0 1 0 5.5 M17 13.5a6 6 0 0 1 4 6"/>',
+    clock: '<circle cx="12" cy="12" r="9"/><path d="M12 7v5l3.5 2"/>',
+    check: '<path d="M5 12.5l4.5 4.5L19 7.5"/>',
+    quote: '<path d="M7 16c-1.5 0-3-1.5-3-3.5S5.5 8 8 7l1 1.5c-1.5.7-2 1.6-2 2.5 1.5 0 2.5 1 2.5 2.5S8.5 16 7 16z ' \
+           'M16 16c-1.5 0-3-1.5-3-3.5S14.5 8 17 7l1 1.5c-1.5.7-2 1.6-2 2.5 1.5 0 2.5 1 2.5 2.5S17.5 16 16 16z"/>',
+    sun: '<circle cx="12" cy="12" r="4"/><path d="M12 3v2 M12 19v2 M3 12h2 M19 12h2 M5.6 5.6l1.4 1.4 M17 17l1.4 1.4 ' \
+         'M5.6 18.4L7 17 M17 7l1.4-1.4"/>'
+  }.freeze
+
+  LIFE = <<~HTML
+    <p>We believe a good month feels natural rather than scheduled. Breakfast is long, the sea is a short walk
+    away and the evenings belong to whoever brings a guitar. Food is not included: guests shop at the Tuesday
+    market, cook for themselves or for everyone, and eat out in the harbour when the mood takes them.</p>
+    <p>Most days follow a loose rhythm:</p>
+    <ul>
+      <li>Morning movement on the terrace before it gets warm</li>
+      <li>Focused work or rest until the early afternoon</li>
+      <li>Swims, hikes and boat trips when the light softens</li>
+      <li>A shared table and a circle on two evenings a week</li>
+    </ul>
+    <p>Every session adapts to who turns up. Nothing is compulsory, and nobody keeps score.</p>
+  HTML
+
+  page size: :a4, margin: MARGIN
+  default_text size: 10, color: INK, leading: 3
+  metadata title: "Harbourside — a month on Ilha Serena", author: "stationery example", lang: "en"
+  tagged
+
+  # A cream page, painted under every page.
+  page_template(layer: :background) do |page|
+    canvas(at: [0, 0], width: page.width, height: page.height) do |c, rect|
+      c.fill_rect(rect.x, rect.y, rect.width, rect.height, color: PAGE)
+    end
+  end
+
+  footer(gap: 12) do |page|
+    text "Harbourside  ·  harbourside.example  ·  Page #{page.number} of #{page.count}",
+         size: 7, color: FAINT, align: :center
+  end
+
+  def self.preview = new
+
+  def view_template
+    hero
+    stats
+    section("Life at Harbourside", band: true)
+    html LIFE, styles: { p: { color: MUTED }, ul: { gap: 3, marker_color: ACCENT, indent: 14 } }
+    spacer 10
+    collage
+    section("What's included")
+    included
+    section("Prices", band: true)
+    prices
+    section("Where you sleep")
+    accommodation
+    section("Impressions", band: true)
+    gallery
+    section("What guests say")
+    testimonials
+    call_to_action
+  end
+
+  private
+
+  # ---- hero ----------------------------------------------------------------
+
+  # The cover photo covers the page's full width and bleeds off the top; the
+  # positioned box takes no flow height, so a spacer reserves the space.
+  def hero
+    box(at: [0, 0], width: page_width) do
+      image photo("sea"), width: page_width, height: COVER_HEIGHT, fit: :cover, alt: "The harbour at first light"
+    end
+    spacer COVER_HEIGHT - MARGIN + 18
+    date_pill
+    spacer 14
+    text "Harbourside", size: 30, weight: :bold, color: PRIMARY, align: :center, heading: 1
+    spacer 4
+    text "A month of community living on Ilha Serena", size: 12, color: MUTED, align: :center
+    spacer 14
+    meta_row
+  end
+
+  def date_pill
+    group(align: :center) do
+      box(width: :auto, background: PRIMARY, radius: 10, padding: [4, 12]) do
+        row(gap: 5, align: :middle) do
+          column(width: :auto) { icon(:calendar, size: 10, color: PRIMARY_CONTENT) }
+          column(width: :auto) { text "3 – 31 May 2027", size: 9, color: PRIMARY_CONTENT }
+        end
+      end
+    end
+  end
+
+  def meta_row
+    row do
+      [[:pin, "Porto Velho, Ilha Serena"], [:users, "12 – 20 guests"], [:clock, "7 to 28 nights"]].each do |name, label|
+        column do
+          row(gap: 5, align: :middle) do
+            column(width: 14, padding: [0, 0, 0, 4]) { icon(name, size: 10) }
+            column { text label, size: 9, color: MUTED }
+          end
+        end
+      end
+    end
+  end
+
+  # ---- stats band ----------------------------------------------------------
+
+  def stats
+    spacer 22
+    box(background: BAND, radius: 12, padding: [14, 10]) do
+      row do
+        [[:clock, "Duration", "7 – 28 nights"], [:sun, "Investment", "from € 690"],
+         [:users, "Group size", "12 – 20 guests"]].each do |name, label, value|
+          column(align: :center) { stat(name, label, value) }
+        end
+      end
+    end
+  end
+
+  def stat(name, label, value)
+    icon_disc(name)
+    spacer 6
+    text label, size: 8, color: FAINT, align: :center
+    spacer 2
+    text value, size: 11, weight: :bold, color: PRIMARY, align: :center
+  end
+
+  def icon_disc(name, diameter: 26)
+    group(align: :center) do
+      box(width: diameter, height: diameter, radius: diameter / 2.0, background: TINT, valign: :middle) do
+        icon(name, size: 13, align: :center)
+      end
+    end
+  end
+
+  # ---- sections ------------------------------------------------------------
+
+  # A section heading, on a full-bleed tinted strip for every other section,
+  # bookmarked in the outline and kept with the start of its section.
+  def section(title, band: false)
+    spacer 18
+    group(keep_with_next: 120, bookmark: title) do
+      if band
+        box(background: BAND, outset: [0, MARGIN, 0, MARGIN], padding: [12, 0]) { heading(title) }
+      else
+        heading(title)
+      end
+      spacer 10
+    end
+  end
+
+  def heading(title) = text(title, size: 19, weight: :bold, color: PRIMARY, align: :center, heading: 2)
+
+  def collage
+    group(align: :center) do
+      box(padding: OVERHANG, width: :auto) do
+        stack do
+          box(width: :auto, radius: 16, shadow: true) do
+            image photo("hills"), width: 300, height: 225, fit: :cover, radius: 16, alt: "Hills above the harbour"
+          end
+          layer(bottom: -OVERHANG, left: -OVERHANG, width: 0.4, rotate: -3, **frame) do
+            image photo("stone"), width: 112, height: 84, fit: :cover, radius: 8, alt: "The old stone quay"
+          end
+          layer(top: -OVERHANG, right: -OVERHANG, width: 1/3r, rotate: 2, **frame) do
+            image photo("bay"), width: 92, height: 92, fit: :cover, radius: 8, alt: "The bay from the terrace"
+          end
+        end
+      end
+    end
+  end
+
+  def frame = { padding: 4, background: "#FFFFFF", radius: 12, shadow: true }
+
+  def included
+    items = ["Your room for the whole stay", "Morning movement, six days a week",
+             "Two evening circles every week", "A boat day and two guided hikes",
+             "A shared kitchen and the Tuesday market run", "Fast Wi-Fi and a quiet room to work in"]
+    items.each_slice(2) do |pair|
+      row(gap: 14) do
+        pair.each do |item|
+          column(width: 0.5) do
+            row(gap: 6) do
+              column(width: 10, padding: [3, 0, 0, 0]) { icon(:check, size: 9, color: ACCENT) }
+              column { text item, size: 10, leading: 2 }
+            end
+          end
+        end
+      end
+      spacer 7
+    end
+  end
+
+  def prices
+    text "Prices are per person and include everything listed above. Children under twelve stay free in " \
+         "their parents' room.", color: MUTED, align: :center
+    spacer 10
+    rows = [["Stay", "Regular", "Early bird\n<font size='7'>until 31 January</font>", "Returning guests"],
+            ["7 nights", "€ 690", "€ 620", "€ 590"], ["14 nights", "€ 1,290", "€ 1,160", "€ 1,090"],
+            ["21 nights", "€ 1,790", "€ 1,610", "€ 1,520"], ["28 nights", "€ 2,190", "€ 1,970", "€ 1,860"]]
+    table(rows, width: :full, header: true,
+                cell: { markup: true, size: 9.5, borders: [:bottom], border_color: HAIRLINE, padding: [6, 8] }) do |t|
+      t.row(0).set(background: PRIMARY, color: PRIMARY_CONTENT, weight: :bold)
+      t.columns(1..).align = :right
+      t.zebra(from: 2, color: BAND)
+    end
+    spacer 8
+    text "Returning guests are anyone who has stayed with us before, in any house.", size: 8.5, color: FAINT,
+                                                                                     align: :center
+  end
+
+  def accommodation
+    [["The Harbour House", "6 rooms · sleeps 10", "ridge",
+      "The old harbourmaster's house: a big kitchen, a walled garden and rooms that look over the boats."],
+     ["The Terrace Apartments", "2 apartments · sleeps 6", "wall",
+      "Two quiet apartments above the square, each with its own kitchen and a terrace that catches the " \
+      "afternoon sun."]].each do |name, capacity, picture, blurb|
+      group(keep_together: true) do
+        row(gap: 14, align: :middle) do
+          column(width: 150) { image photo(picture), width: 150, height: 96, fit: :cover, radius: 10, alt: name }
+          column do
+            text name, size: 13, weight: :bold, color: PRIMARY, heading: 3
+            text capacity, size: 9, color: ACCENT
+            spacer 4
+            text blurb, color: MUTED
+          end
+        end
+      end
+      spacer 14
+    end
+  end
+
+  def gallery
+    %w[sea hills stone bay ridge dunes].each_slice(3) do |names|
+      row(gap: 8) do
+        names.each do |name|
+          column(width: 1 / 3.0) do
+            image photo(name), width: 161, height: 96, fit: :cover, radius: 8, alt: "Impression"
+          end
+        end
+      end
+      spacer 8
+    end
+  end
+
+  def testimonials
+    [["Three weeks in, I stopped checking the time. That has never happened to me on a holiday.", "Mara, Vienna"],
+     ["Came for the sea, stayed for the Tuesday market and the people around the table.", "Jonas, Malmö"]]
+      .each do |quote, author|
+      group(keep_together: true) do
+        box(role: :blockquote, background: BAND, radius: 12, padding: [14, 18]) do
+          icon(:quote, size: 14, color: ACCENT, align: :center)
+          spacer 6
+          text %("#{quote}"), style: :italic, color: MUTED, align: :center
+          spacer 4
+          text author, size: 9, color: PRIMARY, align: :center
+        end
+      end
+      spacer 10
+    end
+  end
+
+  # A pill the whole shape of which is clickable, and the address spelled out
+  # for the printed copy.
+  def call_to_action
+    url = "https://harbourside.example/apply"
+    spacer 22
+    group(keep_together: true) do
+      box(background: BAND, outset: [0, MARGIN, 0, MARGIN], padding: [16, 0]) do
+        text "Ready to come?", size: 19, weight: :bold, color: PRIMARY, align: :center, heading: 2
+        spacer 6
+        text "Applications open until the house is full. We read every one and reply within a week.",
+             color: MUTED, align: :center
+        spacer 12
+        group(align: :center) do
+          box(width: :auto, height: 26, background: PRIMARY, radius: 13, padding: [0, 28], valign: :middle,
+              link: url) do
+            text "Apply for a call", size: 11, color: PRIMARY_CONTENT, align: :center
+          end
+        end
+        spacer 8
+        text(size: 9, align: :center) { |t| t.link(url) { t.color(MUTED, "or write to hello@harbourside.example") } }
+      end
+    end
+  end
+
+  # ---- helpers -------------------------------------------------------------
+
+  def page_width = Stationery::Page.new(size: :a4).width
+  def photo(name) = File.join(ASSETS, "#{name}.png")
+
+  # Decorative line icons; the label beside each one carries the meaning.
+  def icon(name, size: 12, color: PRIMARY, align: nil)
+    svg "#{SVG_OPEN}#{ICONS.fetch(name)}</svg>", width: size, height: size, color:, align:, alt: false
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  flyer = ExampleFlyer.preview
+  flyer.to_pdf(File.expand_path("flyer.pdf", __dir__))
+  warn flyer.warnings.map(&:message) if flyer.warnings.any?
+  puts "wrote examples/flyer.pdf"
+end

data/examples/form.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+# A one-page membership application with every kind of form field: text
+# inputs, a multiline note, a comb field, a select box, a radio group, check
+# boxes and a signature field. Run it to write examples/form.pdf:
+#
+#   ruby -Ilib examples/form.rb
+#   ruby -Ilib exe/stationery render examples/form.rb
+require "stationery"
+
+class ExampleForm < Stationery::Document
+  ACCENT = "#0F766E"
+  INK = "#111827"
+  MUTED = "#6B7280"
+  HAIRLINE = "#E5E7EB"
+  PLANS = { "basic" => "Basic · SEK 290 / year", "pro" => "Pro · SEK 590 / year",
+            "team" => "Team · SEK 1,490 / year" }.freeze
+
+  page size: :a4, margin: [48, 56, 40, 56]
+  default_text size: 9.5, color: INK
+  metadata title: "Membership application", author: "Nordic Makers Guild", creator: "stationery example",
+           lang: "en"
+
+  footer do
+    rule height: 0.5, color: HAIRLINE
+    spacer 6
+    text "Nordic Makers Guild · Box 118, 221 00 Lund · members@makers.example", size: 7.5, color: MUTED,
+                                                                                align: :center
+  end
+
+  def self.preview = new(name: "Astrid Lindqvist", email: "astrid@example.se", plan: "pro")
+
+  def initialize(name: "", email: "", plan: nil)
+    super()
+    @name = name
+    @email = email
+    @plan = plan
+  end
+
+  def view_template
+    text "Membership application", size: 20, weight: :bold, color: ACCENT
+    text "Fill in the form on screen, sign it and send it back to us.", color: MUTED
+    spacer 20
+    applicant
+    spacer 18
+    membership
+    spacer 18
+    consent
+  end
+
+  private
+
+  def heading(title)
+    text title, size: 11, weight: :bold, keep_with_next: true
+    rule height: 0.5, color: HAIRLINE
+    spacer 8
+  end
+
+  def labelled(label)
+    column do
+      text label, size: 8, color: MUTED
+      spacer 3
+      yield
+    end
+  end
+
+  def applicant
+    heading "Applicant"
+    row(gap: 12) do
+      labelled("Full name") { text_field "applicant.name", value: @name, required: true }
+      labelled("Email") { text_field "applicant.email", value: @email, required: true }
+    end
+    spacer 10
+    row(gap: 12) do
+      labelled("Street address") { text_field "applicant.address.street" }
+      column(width: 90) { labelled("Postcode") { text_field "applicant.address.postcode", comb: 5 } }
+      labelled("Country") do
+        select "applicant.address.country", options: %w[Sweden Norway Denmark Finland Iceland], value: "Sweden"
+      end
+    end
+  end
+
+  def membership
+    heading "Membership"
+    PLANS.each do |value, label|
+      radio "plan", value, checked: value == @plan, label: label
+      spacer 4
+    end
+    spacer 8
+    text "Anything we should know? (workshops you are interested in, accessibility needs)", size: 8, color: MUTED
+    spacer 3
+    text_field "notes", multiline: true, height: 70
+  end
+
+  def consent
+    heading "Consent"
+    checkbox "terms", label: "I accept the terms of membership and the workshop safety rules."
+    spacer 4
+    checkbox "newsletter", checked: true, label: "Send me the monthly newsletter."
+    spacer 24
+    row(gap: 24, align: :bottom) do
+      column { signature_field "signature", label: "Signature of the applicant" }
+      column(width: 150) { labelled("Date") { text_field "signed_on" } }
+    end
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  form = ExampleForm.preview
+  form.to_pdf(File.expand_path("form.pdf", __dir__))
+  warn form.warnings.map(&:message) if form.warnings.any?
+  puts "wrote examples/form.pdf"
+end

data/examples/invoice.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+# An invoice: a logo beside an amount-due callout, a summary table without
+# borders, a line-item table with a coloured header, zebra rows and a totals
+# row, in a font family of its own. Run it to write examples/invoice.pdf:
+#
+#   ruby -Ilib examples/invoice.rb
+#   ruby -Ilib exe/stationery render examples/invoice.rb
+require "stationery"
+
+class ExampleInvoice < Stationery::Document
+  FONTS = File.expand_path("../spec/fixtures/fonts", __dir__)
+  LOGO = File.expand_path("assets/logo.png", __dir__)
+
+  ACCENT = "#4F46E5"
+  INK = "#1F2937"
+  MUTED = "#6B7280"
+  HAIRLINE = "#E5E7EB"
+  ZEBRA = "#F9FAFB"
+  CALLOUT = "#F3F4F6"
+
+  # Open Sans lives with the test suite, so an installed gem sets the invoice
+  # in the Inter it bundles.
+  FAMILY = File.exist?(File.join(FONTS, "OpenSans-Regular.ttf")) ? "Open Sans" : "Inter"
+
+  page size: :a4, margin: [40, 44, 56, 44]
+  if FAMILY == "Open Sans"
+    font_family "Open Sans",
+                regular: File.join(FONTS, "OpenSans-Regular.ttf"), bold: File.join(FONTS, "OpenSans-Bold.ttf"),
+                italic: File.join(FONTS, "OpenSans-Italic.ttf"),
+                bold_italic: File.join(FONTS, "OpenSans-BoldItalic.ttf")
+  end
+  default_text font: FAMILY, size: 9, color: INK
+  metadata title: "Invoice", creator: "stationery example"
+
+  page_template do |page|
+    box(at: [page.margin[3], page.height - 34], width: page.content_box.width) do
+      text "Page #{page.number} of #{page.count}", size: 7, color: MUTED, align: :right
+    end
+  end
+
+  def self.preview
+    items = [["Brand workshop", 1, 2400.0], ["Logo design, three concepts", 1, 3200.0],
+             ["Illustration set (12)", 12, 180.0], ["Print-ready files", 1, 450.0], ["Rush delivery", 1, 300.0]]
+    new(number: "INV-2026-042", items:, customer: "Müller & Söhne GmbH", due: "26 October 2026")
+  end
+
+  def initialize(number:, items:, customer:, due:)
+    super()
+    @number = number
+    @items = items
+    @customer = customer
+    @due = due
+  end
+
+  def view_template
+    header
+    spacer 18
+    summary
+    spacer 22
+    parties
+    spacer 26
+    line_items
+    spacer 28
+    footer
+  end
+
+  private
+
+  def header
+    row(align: :middle) do
+      column(width: 0.5) { text "Invoice #{@number}", size: 22, weight: :bold }
+      column(width: 0.5, align: :right) { image LOGO, height: 34, align: :right }
+    end
+    spacer 10
+    rule height: 3, color: ACCENT
+  end
+
+  def summary
+    row(gap: 24) do
+      column do
+        table([["Invoice date", "26 September 2026"], ["Due date", @due], ["Reference", "PO-7781"]],
+              widths: [90, nil], cell: { borders: [], padding: [1, 12, 2, 0], color: MUTED }) do |t|
+          t.column(0).weight = :bold
+          t.column(0).color = INK
+        end
+      end
+      column(width: 190) { amount_due }
+    end
+  end
+
+  def amount_due
+    box(background: CALLOUT, radius: 6, padding: 12) do
+      text "AMOUNT DUE", size: 8, weight: :bold, color: MUTED, letter_spacing: 0.5
+      text money(total), size: 19, weight: :bold, color: ACCENT
+      spacer 6
+      row { column(width: :auto) { status_pill("OPEN", "#3B82F6") } }
+    end
+  end
+
+  def status_pill(label, color)
+    box(background: color, radius: 7, padding: [2, 9]) { text label, size: 7, weight: :bold, color: "#FFFFFF" }
+  end
+
+  def parties
+    row(gap: 24) do
+      column(width: 0.5) do
+        party("FROM", ["<b>Acme Studio AB</b>", "Storgatan 1", "111 22 Stockholm", "hello@acme.test"])
+      end
+      column(width: 0.5) { party("BILL TO", ["<b>#{@customer}</b>", "Hauptstraße 5", "10115 Berlin"]) }
+    end
+  end
+
+  def party(label, lines)
+    text label, size: 8, weight: :bold, color: MUTED, letter_spacing: 0.5
+    spacer 3
+    text lines.join("\n"), markup: true, leading: 1
+  end
+
+  def line_items
+    rows = [%w[Description Qty Price VAT Amount]]
+    @items.each { |name, qty, price| rows << [name, qty.to_s, money(price), "25%", money(qty * price)] }
+    rows << ["", "", "", "Subtotal", money(subtotal)]
+    rows << ["", "", "", "VAT 25%", money(vat)]
+    rows << ["", "", "", "Total", money(total)]
+    count = @items.size
+
+    table(rows, width: :full, widths: [nil, 45, 80, 60, 85], header: true,
+                cell: { padding: [7, 8], borders: [] }) do |t|
+      t.row(0).set(background: ACCENT, color: "#FFFFFF", weight: :bold)
+      t.columns(1..).align = :right
+      t.zebra(from: 2, to: count, color: ZEBRA)
+      t.row(count + 1).columns(3..).set(borders: [:top], border_color: HAIRLINE, border_width: 1)
+      t.row(-1).set(weight: :bold, size: 11)
+    end
+  end
+
+  def footer
+    group(keep_together: true) do
+      rule height: 1, color: HAIRLINE
+      spacer 14
+      text "Thank you for your business", size: 9, weight: :bold
+      spacer 3
+      text "Pay to IBAN SE45 5000 0000 0583 9825 7466 within 30 days. Questions? " \
+           "<link href='mailto:hello@acme.test'><color rgb='#{ACCENT}'>hello@acme.test</color></link>",
+           markup: true, size: 8.5, color: MUTED, leading: 2
+    end
+  end
+
+  def subtotal = @items.sum { |_, qty, price| qty * price }
+  def vat = (subtotal * 0.25).round(2)
+  def total = subtotal + vat
+
+  def money(amount)
+    whole, cents = format("%.2f", amount).split(".")
+    "€#{whole.reverse.scan(/\d{1,3}/).join(" ").reverse},#{cents}"
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  ExampleInvoice.preview.to_pdf(File.expand_path("invoice.pdf", __dir__))
+  puts "wrote examples/invoice.pdf"
+end