stationery 0.11.0 → 0.12.0

data/examples/letter.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+# A one-page business letter with a vector letterhead. Run it to write
+# examples/letter.pdf:
+#
+#   ruby -Ilib examples/letter.rb
+#   ruby -Ilib exe/stationery render examples/letter.rb
+require "stationery"
+
+class ExampleLetter < Stationery::Document
+  ACCENT = "#B45309"
+  INK = "#1C1917"
+  MUTED = "#78716C"
+  HAIRLINE = "#E7E5E4"
+  LOGO = <<~SVG
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 40 40">
+      <rect width="40" height="40" rx="9" fill="#B45309"/>
+      <path d="M11 28V12l9 10 9-10v16" fill="none" stroke="#FFFFFF" stroke-width="3.2"
+            stroke-linecap="round" stroke-linejoin="round"/>
+      <circle cx="20" cy="31" r="2.2" fill="#FDE68A"/>
+    </svg>
+  SVG
+
+  page size: :a4, margin: [48, 64, 40, 64]
+  default_text size: 10.5, color: INK
+  metadata title: "Letter to Hallberg Bygg AB", author: "Mälaren Studio AB", creator: "stationery example"
+
+  footer do
+    rule height: 0.5, color: HAIRLINE
+    spacer 6
+    text "Mälaren Studio AB · Org. nr 559123-4567 · VAT SE559123456701 · Registered office Västerås, Sweden",
+         size: 7.5, color: MUTED, align: :center
+  end
+
+  def self.preview
+    new(recipient: ["Ms Anna Hallberg", "Hallberg Bygg AB", "Kungsgatan 12", "753 21 Uppsala"],
+        date: "27 September 2026", reference: "Proposal MS-2026-118")
+  end
+
+  def initialize(recipient:, date:, reference:)
+    super()
+    @recipient = recipient
+    @date = date
+    @reference = reference
+  end
+
+  def view_template
+    letterhead
+    spacer 56
+    row do
+      column(width: 0.6) { text @recipient.join("\n"), leading: 2 }
+      column(width: 0.4) { text "Västerås, #{@date}\nOur ref. #{@reference}", color: MUTED, align: :right, leading: 2 }
+    end
+    spacer 40
+    text "Proposal for the redesign of your customer portal", size: 12, weight: :bold
+    spacer 16
+    body
+    spacer 28
+    signature
+  end
+
+  private
+
+  def letterhead
+    row(align: :middle, gap: 12) do
+      column(width: 40) { svg LOGO, width: 40 }
+      column do
+        text "Mälaren Studio", size: 15, weight: :bold
+        text "Stora Gatan 21, 722 12 Västerås", size: 8.5, color: MUTED
+      end
+      column(width: 160) do
+        text_style(size: 8.5, color: MUTED, align: :right, leading: 1.5) do
+          text "+46 21 123 45 67"
+          text "hello@malaren.studio"
+          text "malaren.studio"
+        end
+      end
+    end
+    spacer 12
+    rule height: 2, color: ACCENT
+  end
+
+  def body
+    text_style(align: :justify, leading: 4) do
+      [
+        "Dear Ms Hallberg,",
+        "Thank you for meeting us in Uppsala last week and for walking us through the way your site managers " \
+        "use the customer portal today. It was clear that the portal holds the right information but makes it " \
+        "hard to find: most of the questions your office answers by phone are already answered somewhere in it.",
+        "We propose a redesign in <b>three phases over twelve weeks</b>. The first phase maps the ten most " \
+        "common tasks with your customers and staff; the second turns them into a clickable prototype that we " \
+        "test on site; the third delivers the finished design and supports your developers while they build it.",
+        "The fixed price for all three phases is <b>SEK 480,000</b> excluding VAT, invoiced at the end of each " \
+        "phase. The full proposal, with the schedule and the people involved, is available at " \
+        "<link href='https://malaren.studio/p/MS-2026-118'><color rgb='#{ACCENT}'><u>malaren.studio/p/MS-2026-118</u>" \
+        "</color></link>.",
+        "We would be glad to start in the week of 2 November. If you have any questions, or would like to " \
+        "adjust the scope, please call me directly on the number above."
+      ].each_with_index do |paragraph, index|
+        spacer 10 if index.positive?
+        text paragraph, markup: true
+      end
+    end
+  end
+
+  def signature
+    group(keep_together: true) do
+      text "Kind regards,"
+      spacer 30
+      text "Erik Sandberg", weight: :bold
+      text "Creative Director, Mälaren Studio AB", color: MUTED, size: 9.5
+    end
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  letter = ExampleLetter.preview
+  letter.to_pdf(File.expand_path("letter.pdf", __dir__))
+  warn letter.warnings.map(&:message) if letter.warnings.any?
+  puts "wrote examples/letter.pdf"
+end

data/examples/menu.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+# A restaurant menu on one page: an introduction wrapped around a floated
+# photo, the dishes poured through two balanced columns, a floated box for
+# the dish of the day, and headings set in the heavier weights of Inter. Run
+# it to write examples/menu.pdf:
+#
+#   ruby -Ilib examples/menu.rb
+#   ruby -Ilib exe/stationery render examples/menu.rb
+#
+# The type is the bundled Inter. For a font pack, install it
+# (`stationery fonts install noto_serif`) and name it:
+# `font_family "Noto Serif"`, then `default_text font: "Noto Serif"`.
+require "stationery"
+
+class ExampleMenu < Stationery::Document
+  PHOTO = File.expand_path("assets/bay.png", __dir__)
+  INK = "#1C1917"
+  MUTED = "#78716C"
+  ACCENT = "#9A3412"
+  CREAM = "#FFF7ED"
+  LINE = "#E7E5E4"
+
+  COURSES = {
+    "Starters" => [
+      ["Smoked mackerel", "Rye crisp, pickled cucumber, horseradish cream", 145],
+      ["Beetroot tartare", "Goat's cheese, walnuts, dill oil", 135],
+      ["Fish soup", "Saffron broth, mussels, aioli, toasted sourdough", 165],
+      ["Chanterelles on toast", "Brown butter, thyme, aged cheese", 155]
+    ],
+    "Mains" => [
+      ["Pan-fried cod", "Brown butter, capers, new potatoes, peas", 295],
+      ["Slow-cooked lamb", "Root vegetables, rosemary jus, crispy kale", 325],
+      ["Barley risotto", "Mushrooms, parsley, pecorino, lemon", 245],
+      ["Char with sorrel sauce", "Fennel, dill potatoes, roe", 310],
+      ["Harbour burger", "Aged beef, cheddar, onions, fries", 225]
+    ],
+    "Desserts" => [
+      ["Cloudberry parfait", "Almond crumble, warm cloudberries", 125],
+      ["Chocolate cake", "Sea salt, crème fraîche", 115],
+      ["Cheese from the island", "Three cheeses, crispbread, quince", 145]
+    ],
+    "To drink" => [
+      ["House lemonade", "Elderflower or rhubarb", 55],
+      ["Local cider", "Dry, 33 cl", 85],
+      ["Coffee or tea", "Refills are free", 40]
+    ],
+    "Wine by the glass" => [
+      ["Grüner Veltliner", "Crisp and peppery, with the fish", 125],
+      ["Pinot noir", "Light and red-fruited, with the lamb", 135],
+      ["Sparkling cider", "Méthode traditionnelle, from the island", 110]
+    ]
+  }.freeze
+
+  page size: :a4, margin: [56, 56, 48, 56]
+  default_text size: 9.5, color: INK, leading: 2
+  metadata title: "Menu · The Harbour Kitchen", author: "The Harbour Kitchen", creator: "stationery example"
+
+  def self.preview = new(special: ["Grilled herring", "Mustard sauce, mashed potatoes, lingonberries", 185])
+
+  def initialize(special:)
+    super()
+    @special = special
+  end
+
+  def view_template
+    masthead
+    introduction
+    spacer 16
+    # One flow of courses poured through two columns: column one top to
+    # bottom, then column two, ending level where the dishes run out.
+    columns(count: 2, gap: 28, rule: { color: LINE }) do
+      COURSES.each { |course, dishes| course(course, dishes) }
+    end
+    spacer 14
+    rule color: LINE
+    spacer 6
+    text "Tell us about allergies before you order. All prices in SEK, service included.",
+         size: 8, color: MUTED, align: :center
+  end
+
+  private
+
+  def masthead
+    text "THE HARBOUR KITCHEN", size: 10, weight: :bold, color: ACCENT, letter_spacing: 3, align: :center
+    spacer 4
+    text "Autumn menu", size: 34, weight: :bold, align: :center
+    spacer 14
+  end
+
+  # The photo floats left and the text wraps beside it; the dish of the day
+  # floats right, between them, in a box of its own.
+  def introduction
+    image PHOTO, float: :left, width: 0.34, height: 104, fit: :cover, radius: 6, margin: 14
+    box(float: :right, width: 150, margin: { left: 14, bottom: 6 }, background: CREAM, radius: 6, padding: 10) do
+      text "DISH OF THE DAY", size: 7, weight: :bold, color: ACCENT, letter_spacing: 1
+      spacer 3
+      name, description, price = @special
+      text name, size: 11, weight: :bold
+      text description, size: 8.5, color: MUTED
+      spacer 3
+      text price.to_s, weight: :bold, color: ACCENT
+    end
+    text "Everything on this menu comes from within a day's drive of the harbour: the fish from the boats " \
+         "you can see from your table, the vegetables from two farms on the island and the cheese from the " \
+         "dairy up the hill. The menu changes with the catch and the season, so some dishes may run out " \
+         "before the evening does.", align: :justify, hyphenate: true, size: 10.5, leading: 3
+  end
+
+  # A course is kept together, so a column never starts in the middle of one.
+  def course(title, dishes)
+    group(keep_together: true) do
+      text title, size: 18, weight: :bold, color: ACCENT
+      spacer 8
+      dishes.each do |name, description, price|
+        row(gap: 8) do
+          column { text name, size: 10.5, weight: :bold }
+          column(width: :auto) { text price.to_s, size: 10.5, weight: :bold }
+        end
+        text description, size: 9, color: MUTED, style: :italic
+        spacer 10
+      end
+      spacer 14
+    end
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  menu = ExampleMenu.preview
+  menu.to_pdf(File.expand_path("menu.pdf", __dir__))
+  warn menu.warnings.map(&:message) if menu.warnings.any?
+  puts "wrote examples/menu.pdf"
+end

data/examples/multilingual_notice.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+# A notice to residents in English, German and Swedish side by side, each
+# column justified and hyphenated by the patterns of its own language, with
+# a Japanese paragraph when a CJK font is at hand. Run it to write
+# examples/multilingual_notice.pdf:
+#
+#   ruby -Ilib examples/multilingual_notice.rb
+#   ruby -Ilib exe/stationery render examples/multilingual_notice.rb
+#
+# Inter, the font the gem bundles, has Latin, Greek and Cyrillic but no CJK
+# ideographs, and no font pack has them either. Name a font that has them to
+# add the Japanese paragraph; it is registered as a fallback, so it draws only
+# the characters Inter lacks, and the lines break between ideographs:
+#
+#   CJK_FONT=/path/to/NotoSansJP-Regular.ttf ruby -Ilib examples/multilingual_notice.rb
+require "stationery"
+
+class ExampleMultilingualNotice < Stationery::Document
+  ACCENT = "#0E7490"
+  INK = "#111827"
+  MUTED = "#6B7280"
+  PANEL = "#ECFEFF"
+  CJK_FONT = ENV.fetch("CJK_FONT", nil)
+
+  # Each language with the hyphenation patterns to break its words by:
+  # `true` is American English, "de" German and "sv" Swedish.
+  NOTICES = [
+    ["English", true, "Water will be turned off",
+     ["The water supply to every flat in the building will be turned off on Tuesday 14 October between " \
+      "08:00 and 16:00 while the main distribution pipes in the basement are replaced.",
+      "Please fill a few containers with drinking water beforehand and keep the taps closed during the " \
+      "work. Discoloured water may run for a short while afterwards; let the cold tap run until it is clear."]],
+    ["Deutsch", "de", "Das Wasser wird abgestellt",
+     ["Am Dienstag, dem 14. Oktober, wird die Wasserversorgung aller Wohnungen im Gebäude zwischen 08:00 " \
+      "und 16:00 Uhr unterbrochen, da die Hauptverteilungsleitungen im Keller erneuert werden.",
+      "Bitte füllen Sie vorher einige Behälter mit Trinkwasser und lassen Sie die Wasserhähne während der " \
+      "Arbeiten geschlossen. Danach kann das Wasser kurzzeitig verfärbt sein; lassen Sie das kalte Wasser " \
+      "laufen, bis es klar ist."]],
+    ["Svenska", "sv", "Vattnet stängs av",
+     ["Tisdagen den 14 oktober stängs vattnet av i alla lägenheter i huset mellan klockan 08.00 och 16.00, " \
+      "medan huvudledningarna i källaren byts ut.",
+      "Fyll gärna några kärl med dricksvatten i förväg och håll kranarna stängda under arbetet. Efteråt kan " \
+      "vattnet vara missfärgat en kort stund; spola kallvatten tills det är klart."]]
+  ].freeze
+
+  JAPANESE = "10月14日（火）8時から16時まで、地下の給水管の交換工事のため、建物内のすべての住戸で断水します。" \
+             "事前に飲料水をご用意いただき、工事中は蛇口を閉めておいてください。工事後、しばらく濁った水が出ることが" \
+             "ありますので、透明になるまで水を流してください。"
+
+  page size: :a4, margin: [52, 48, 44, 48]
+  default_text font: "Inter", size: 10.5, color: INK, leading: 3
+  metadata title: "Notice to residents", author: "Example Housing Cooperative", creator: "stationery example"
+
+  # A font for what Inter lacks: drawn only where Inter has no glyph.
+  if CJK_FONT
+    font_family "CJK", regular: CJK_FONT
+    font_fallbacks "CJK"
+  end
+
+  def self.preview = new
+
+  def view_template
+    text "NOTICE · HINWEIS · MEDDELANDE", size: 9, weight: :bold, color: ACCENT, letter_spacing: 2
+    spacer 6
+    text "Harbour View Housing Cooperative, 1–5 Example Street", size: 10, color: MUTED
+    spacer 8
+    rule height: 2, color: ACCENT
+    spacer 16
+    row(gap: 18) do
+      NOTICES.each do |language, hyphenate, title, paragraphs|
+        column { notice(language, hyphenate, title, paragraphs) }
+      end
+    end
+    spacer 18
+    japanese
+    spacer 18
+    contact
+  end
+
+  private
+
+  def notice(language, hyphenate, title, paragraphs)
+    text language.upcase, size: 7.5, weight: :bold, color: MUTED, letter_spacing: 1
+    spacer 4
+    text title, size: 15, weight: :bold, color: ACCENT
+    spacer 6
+    paragraphs.each do |paragraph|
+      text paragraph, align: :justify, hyphenate: hyphenate
+      spacer 6
+    end
+  end
+
+  def japanese
+    box(background: PANEL, radius: 6, padding: 12) do
+      text "JAPANESE", size: 7.5, weight: :bold, color: MUTED, letter_spacing: 1
+      spacer 4
+      if CJK_FONT
+        text JAPANESE, leading: 4 # Inter for the digits, the CJK font for the rest
+      else
+        text "Japanese: set CJK_FONT to a font with Japanese glyphs to include this paragraph. Inter, the " \
+             "font in the gem, has none; see the comment at the top of examples/multilingual_notice.rb.",
+             size: 8.5, color: MUTED
+      end
+    end
+  end
+
+  def contact
+    rule color: "#E5E7EB"
+    spacer 6
+    text "Questions · Fragen · Frågor: caretaker@harbour-view.example · +46 31 000 00 00",
+         size: 8.5, color: MUTED, align: :center
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  notice = ExampleMultilingualNotice.preview
+  notice.to_pdf(File.expand_path("multilingual_notice.pdf", __dir__))
+  warn notice.warnings.map(&:message) if notice.warnings.any?
+  puts "wrote examples/multilingual_notice.pdf"
+end

data/examples/newsletter.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+# A one-page newsletter: a masthead across the page, an article poured
+# through two balanced columns with headings and a photo, and a footer note
+# across the page below the columns.
+# Run it to write examples/newsletter.pdf:
+#
+#   ruby -Ilib examples/newsletter.rb
+#   ruby -Ilib exe/stationery render examples/newsletter.rb
+require "stationery"
+
+class ExampleNewsletter < Stationery::Document
+  ASSETS = File.expand_path("assets", __dir__)
+  INK = "#1F2937"
+  MUTED = "#6B7280"
+  ACCENT = "#0F766E"
+  LINE = "#D1D5DB"
+
+  ARTICLE = [
+    [nil, ["The harbour wall that has kept the winter swell out of the village since 1911 was reopened on " \
+           "Saturday, eighteen months after a storm took forty metres of it into the bay. Two hundred people " \
+           "walked its length behind the brass band, and the first boat through the gap was the oldest in the " \
+           "fleet.",
+           "The rebuilt section stands a metre higher than the old one. Its core is concrete, but the face is " \
+           "the original sandstone: divers recovered nine blocks in ten from the seabed, and the quarry above " \
+           "the village was opened for a month to cut the rest."]],
+    ["What it cost", ["The work came to 2.4 million, a third of it raised by the village itself. The harbour " \
+                      "dues will rise by four per cent a year until 2031 to repay the loan, a rise the " \
+                      "fishing cooperative voted for without a single vote against.",
+                      "Nothing was spent on the lighthouse, which needs a new lantern. The council has asked " \
+                      "for tenders and expects to decide in the spring."]],
+    ["What comes next", ["The inner quay is next. Its timber piles date from the fifties and the survey gives " \
+                         "them ten years at most. Plans go on show in the old customs house in March, and " \
+                         "the council wants comments before the summer.",
+                         "Until then the wall is open to walkers from dawn to dusk. The gate at the landward " \
+                         "end is locked in any wind above force seven."]]
+  ].freeze
+
+  page size: :a4, margin: 48
+  default_text size: 10, color: INK, leading: 2.5
+  metadata title: "The Harbour Letter", author: "stationery example", lang: "en"
+  tagged
+
+  def self.preview = new
+
+  def view_template
+    masthead
+    columns(count: 2, gap: 22, rule: { color: LINE }) { article }
+    note
+  end
+
+  private
+
+  def masthead
+    text "THE HARBOUR LETTER", size: 9, weight: :bold, color: ACCENT, letter_spacing: 1.5
+    spacer 6
+    text "The sea wall is whole again", size: 30, weight: :bold, leading: 0, heading: 1
+    spacer 6
+    text "Issue 42 · October 2026", size: 9, color: MUTED
+    spacer 10
+    rule height: 2, color: ACCENT
+    spacer 16
+  end
+
+  def article
+    ARTICLE.each_with_index do |(title, paragraphs), index|
+      section_heading(title) if title
+      paragraphs.each { |paragraph| body(paragraph) }
+      photo if index.zero?
+    end
+  end
+
+  def section_heading(title)
+    text title, size: 13, weight: :bold, color: ACCENT, leading: 0, heading: 2, keep_with_next: true
+    spacer 5
+  end
+
+  def body(paragraph)
+    text paragraph, align: :justify, hyphenate: true, orphans: 2, widows: 2
+    spacer 8
+  end
+
+  def photo
+    group(keep_together: true) do
+      image File.join(ASSETS, "bay.png"), width: 1.0, height: 120, fit: :cover, radius: 6,
+                                          alt: "The bay seen from the rebuilt wall"
+      spacer 4
+      text "The bay from the new section of the wall.", size: 8, color: MUTED, style: :italic
+    end
+    spacer 8
+  end
+
+  def note
+    spacer 16
+    rule color: LINE
+    spacer 8
+    text "The Harbour Letter is written by volunteers and printed by the cooperative. Letters to the " \
+         "editor are welcome at the customs house, where back issues are kept.",
+         size: 8.5, color: MUTED, align: :center
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  newsletter = ExampleNewsletter.preview
+  newsletter.to_pdf(File.expand_path("newsletter.pdf", __dir__))
+  warn newsletter.warnings.map(&:message) if newsletter.warnings.any?
+  puts "wrote examples/newsletter.pdf"
+end

data/examples/packing_slip.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+# A landscape packing slip: a long table that repeats its header on every
+# page and a barcode drawn on a canvas. Run it to write examples/packing_slip.pdf:
+#
+#   ruby -Ilib examples/packing_slip.rb
+#   ruby -Ilib exe/stationery render examples/packing_slip.rb
+require "stationery"
+
+class ExamplePackingSlip < Stationery::Document
+  ACCENT = "#1D4ED8"
+  INK = "#111827"
+  MUTED = "#6B7280"
+  HAIRLINE = "#E5E7EB"
+  ZEBRA = "#F3F4F6"
+  PANEL = "#F9FAFB"
+
+  PRODUCTS = ["Hex bolt M8 × 40, zinc plated", "Washer M8, stainless A2", "Cable tie 200 mm, black",
+              "Wall plug 8 mm", "Wood screw 5 × 60, Torx", "Hinge 90 mm, brushed steel",
+              "Shelf bracket 200 × 250 mm, white powder coat, including screws and wall plugs for concrete",
+              "Drawer runner 450 mm, soft close", "Threaded rod M10 × 1000", "Nylon lock nut M10",
+              "Corner brace 40 mm", "Cabinet handle 128 mm, matt black aluminium, for doors up to 22 mm thick"].freeze
+
+  page size: :a4, layout: :landscape, margin: [36, 40, 32, 40]
+  default_text size: 9, color: INK
+  metadata title: "Packing slip", creator: "stationery example"
+
+  header(gap: 14) do |page|
+    row(align: :bottom) do
+      text "Packing slip · Order NW-2026-004817", size: 13, weight: :bold
+      text "Page #{page.number} of #{page.count}", size: 8, color: MUTED, align: :right
+    end
+    spacer 6
+    rule height: 1.5, color: ACCENT
+  end
+
+  footer { text "Check the contents against this slip within 5 days of delivery.", size: 7, color: MUTED }
+
+  def self.preview
+    items = Array.new(120) do |i|
+      sku = "NW-#{10_000 + (i * 37)}"
+      bin = "#{"ABCDEF"[i % 6]}-#{((i % 14) + 1).to_s.rjust(2, "0")}"
+      [sku, PRODUCTS[i % PRODUCTS.size], bin, ((i * 7) % 24) + 1, (((i * 13) % 40) + 5) / 10.0]
+    end
+    new(order: "NW-2026-004817", items:,
+        ship_to: ["Hallberg Bygg AB", "Goods reception, gate 4", "Industrigatan 8", "753 23 Uppsala", "Sweden"],
+        bill_to: ["Hallberg Bygg AB", "Accounts payable", "Box 1204", "751 42 Uppsala", "Sweden"])
+  end
+
+  def initialize(order:, items:, ship_to:, bill_to:)
+    super()
+    @order = order
+    @items = items
+    @ship_to = ship_to
+    @bill_to = bill_to
+  end
+
+  def view_template
+    row(gap: 16) do
+      column(width: 0.35) { address("SHIP TO", @ship_to) }
+      column(width: 0.35) { address("BILL TO", @bill_to) }
+      column { barcode }
+    end
+    spacer 18
+    items_table
+  end
+
+  private
+
+  def address(label, lines)
+    box(background: PANEL, border: { color: HAIRLINE, width: 1 }, radius: 6, padding: [10, 12]) do
+      text label, size: 7.5, weight: :bold, color: MUTED, letter_spacing: 0.6
+      spacer 4
+      text "<b>#{lines.first}</b>\n#{lines.drop(1).join("\n")}", markup: true, leading: 1.5
+    end
+  end
+
+  def barcode
+    digits = @order.delete("^0-9").chars.map(&:to_i)
+    canvas(height: 40) do |canvas, rect|
+      x = rect.x
+      digits.cycle(3).each_with_index do |digit, index|
+        width = 1 + (digit % 3)
+        canvas.fill_rect(x, rect.y, width, rect.height, color: INK) if index.even?
+        x += width + 1
+      end
+    end
+    spacer 4
+    text @order, size: 8, color: MUTED, letter_spacing: 2
+    spacer 8
+    text "Shipped 27 September 2026 · 3 parcels · Example Freight", size: 8, color: MUTED
+  end
+
+  def items_table
+    rows = [["SKU", "Description", "Bin", "Qty", "Unit (kg)", "Weight (kg)"]]
+    @items.each do |sku, name, bin, qty, weight|
+      rows << [sku, name, bin, qty.to_s, kilograms(weight), kilograms(qty * weight)]
+    end
+    rows << [{ content: "#{@items.size} lines", colspan: 3 }, @items.sum { |item| item[3] }.to_s, "",
+             kilograms(@items.sum { |*, qty, weight| qty * weight })]
+
+    table(rows, header: true, split_rows: true, width: :full, widths: [80, 300, nil, 60, 70, 80],
+                cell: { padding: [2.5, 8], borders: [], size: 8.5 }) do |t|
+      t.row(0).set(background: ACCENT, color: "#FFFFFF", weight: :bold)
+      t.columns(0).rows(1..).color = MUTED
+      t.columns(3..).align = :right
+      t.zebra(from: 1, to: @items.size, color: ZEBRA)
+      t.row(-1).set(weight: :bold, color: INK, borders: [:top], border_color: INK, border_width: 1)
+    end
+  end
+
+  def kilograms(value) = format("%.1f", value)
+end
+
+if $PROGRAM_NAME == __FILE__
+  slip = ExamplePackingSlip.preview
+  slip.to_pdf(File.expand_path("packing_slip.pdf", __dir__))
+  warn slip.warnings.map(&:message) if slip.warnings.any?
+  puts "wrote examples/packing_slip.pdf"
+end

data/examples/postcard.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+# An A5 landscape postcard: a photo collage of one large picture with two
+# tilted, white-framed snapshots overlapping its corners, beside a greeting.
+# Run it to write examples/postcard.pdf:
+#
+#   ruby -Ilib examples/postcard.rb
+#   ruby -Ilib exe/stationery render examples/postcard.rb
+require "stationery"
+
+class ExamplePostcard < Stationery::Document
+  ASSETS = File.expand_path("assets", __dir__)
+  PAPER = "#FFFBEB"
+  INK = "#1F2937"
+  MUTED = "#6B7280"
+  ACCENT = "#B45309"
+  OVERHANG = 18
+
+  page size: :a5, layout: :landscape, margin: 36
+  default_text size: 10.5, color: INK
+  metadata title: "Greetings from Sardinia", author: "stationery example", lang: "en"
+  tagged
+
+  # Cream card stock: a background layer 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: PAPER)
+    end
+  end
+
+  def self.preview = new
+
+  def view_template
+    spacer 30
+    row(gap: 20, align: :middle) do
+      column(width: 0.55) { collage }
+      column { greeting }
+    end
+  end
+
+  private
+
+  # The site-style collage: a base photo with rounded corners and a shadow, a
+  # 4:3 snapshot hanging off the bottom-left corner and a square one off the
+  # top-right, each tilted in its white frame. The stack's layers overhang by
+  # OVERHANG points, so the box around it keeps them on the page.
+  def collage
+    box(padding: OVERHANG) do
+      stack do
+        box(width: :auto, radius: 16, shadow: true) do
+          image photo("sea"), width: 228, height: 171, fit: :cover, radius: 16, alt: "The bay at dawn"
+        end
+        layer(bottom: -OVERHANG, left: -OVERHANG, width: 0.4, rotate: -3, **frame) do
+          image photo("hills"), width: 83, height: 62, fit: :cover, radius: 8, alt: "Hills above the village"
+        end
+        layer(top: -OVERHANG, right: -OVERHANG, width: 1/3r, rotate: 2, **frame) do
+          image photo("stone"), width: 68, height: 68, fit: :cover, radius: 8, alt: "A sandstone wall"
+        end
+      end
+    end
+  end
+
+  def frame = { padding: 4, background: "#FFFFFF", radius: 12, shadow: true }
+  def photo(name) = File.join(ASSETS, "#{name}.png")
+
+  def greeting
+    text "Greetings from Sardinia", size: 22, weight: :bold, color: ACCENT, heading: 1
+    spacer 6
+    text "October 2026", size: 9, color: MUTED
+    spacer 14
+    text "The sea is still warm enough to swim before breakfast, the hills smell of myrtle and the village " \
+         "square fills up every evening. Wish you were here.", leading: 3
+    spacer 14
+    text "With love, the whole crew", style: :italic, color: MUTED
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  postcard = ExamplePostcard.preview
+  postcard.to_pdf(File.expand_path("postcard.pdf", __dir__))
+  warn postcard.warnings.map(&:message) if postcard.warnings.any?
+  puts "wrote examples/postcard.pdf"
+end