stationery 0.11.0 → 0.12.0

data/examples/resume.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+# A one-page résumé in two columns of unequal width: a tinted sidebar with
+# contact links and skills, and the experience written as HTML, the way it
+# comes out of a rich-text editor. Run it to write examples/resume.pdf:
+#
+#   ruby -Ilib examples/resume.rb
+#   ruby -Ilib exe/stationery render examples/resume.rb
+require "stationery"
+
+class ExampleResume < Stationery::Document
+  ACCENT = "#2563EB"
+  INK = "#111827"
+  MUTED = "#6B7280"
+  SIDEBAR = "#F1F5F9"
+
+  # What the person wrote in the application's editor: `html` reads it with
+  # the styles given below, and turns its links into links.
+  EXPERIENCE = <<~HTML
+    <style>.when { color: #6B7280; font-size: 8.5pt }</style>
+    <h2>Profile</h2>
+    <p>Engineer who likes the unglamorous parts of logistics software: the queues, the retries and the
+    documents at the end of them. Ten years of Ruby, most of them with a pager.</p>
+    <h2>Experience</h2>
+    <h3>Lead engineer · Harbour Logistics, Gothenburg</h3>
+    <p class="when">2022 – today</p>
+    <p>Leads a team of six building the routing platform that plans 40,000 deliveries a day.</p>
+    <ul>
+      <li>Moved route planning from a nightly batch to <b>live replanning</b>, cutting late deliveries by a third.</li>
+      <li>Introduced contract tests between the eleven services the platform is made of.</li>
+      <li>Mentors two engineers a year through the company's <a href="https://harbour-logistics.example/graduates">graduate programme</a>.</li>
+    </ul>
+    <h3>Software engineer · Northwind Freight, Malmö</h3>
+    <p class="when">2018 – 2022</p>
+    <p>Built the customer portal and the <i>proof of delivery</i> service, from the first commit to
+    two million documents a month.</p>
+    <ul>
+      <li>Replaced a PDF service in Java with one in Ruby that renders in a tenth of the time.</li>
+      <li>Ran the on-call rotation for the portal and wrote its runbooks.</li>
+    </ul>
+    <h3>Junior developer · Example Studio, Lund</h3>
+    <p class="when">2016 – 2018</p>
+    <p>Web shops and booking systems for small businesses in southern Sweden.</p>
+    <h2>Education</h2>
+    <h3>MSc Computer Science · Lund University</h3>
+    <p class="when">2011 – 2016</p>
+    <p>Thesis on incremental layout of long documents, graded with distinction.</p>
+  HTML
+
+  STYLES = {
+    h2: { size: 13, color: ACCENT }, h3: { size: 10.5 }, p: { color: INK },
+    a: { color: ACCENT }, ul: { gap: 3, marker_color: ACCENT }
+  }.freeze
+
+  page size: :a4, margin: [44, 44, 40, 44]
+  default_text size: 9.5, color: INK, leading: 2
+  metadata title: "Résumé of Kim Example", author: "Kim Example", creator: "stationery example"
+
+  def self.preview
+    new(name: "Kim Example", title: "Lead software engineer",
+        contact: [["kim@example.com", "mailto:kim@example.com"], ["+46 70 000 00 00", "tel:+46700000000"],
+                  ["kim.example.com", "https://kim.example.com"], ["Gothenburg, Sweden", nil]],
+        skills: %w[Ruby Rails PostgreSQL Kafka Kubernetes Terraform TypeScript],
+        languages: [%w[Swedish native], %w[English fluent], %w[German good]])
+  end
+
+  def initialize(name:, title:, contact:, skills:, languages:)
+    super()
+    @name = name
+    @title = title
+    @contact = contact
+    @skills = skills
+    @languages = languages
+  end
+
+  def view_template
+    text @name, size: 28, weight: :bold
+    text @title, size: 12, color: ACCENT
+    spacer 18
+    # A sidebar of 30 % and a body that takes the rest: `width:` is a share
+    # of the row, and a column without one takes what is left.
+    row(gap: 24) do
+      column(width: 0.3) { sidebar }
+      column { html EXPERIENCE, styles: STYLES, gap: 5 }
+    end
+  end
+
+  private
+
+  def sidebar
+    box(background: SIDEBAR, radius: 6, padding: 14) do
+      label "CONTACT"
+      @contact.each do |shown, target|
+        text shown, link: target, color: target ? ACCENT : INK, size: 9
+        spacer 2
+      end
+      spacer 12
+      label "SKILLS"
+      wrap(gap: 4, row_gap: 4) do
+        @skills.each do |skill|
+          box(width: :auto, background: "#FFFFFF", radius: 8, padding: [2, 7]) { text skill, size: 8 }
+        end
+      end
+      spacer 12
+      label "LANGUAGES"
+      @languages.each { |language, level| text "<b>#{language}</b>, #{level}", markup: true, size: 9 }
+    end
+  end
+
+  def label(title)
+    text title, size: 7.5, weight: :bold, color: MUTED, letter_spacing: 0.8
+    spacer 5
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  resume = ExampleResume.preview
+  resume.to_pdf(File.expand_path("resume.pdf", __dir__))
+  warn resume.warnings.map(&:message) if resume.warnings.any?
+  puts "wrote examples/resume.pdf"
+end

data/examples/shaping/extraction_matrix/pdfium.py

@@ -0,0 +1,8 @@
+# The text of a PDF as PDFium reads it (FPDFText_GetText, what Chrome copies): python pdfium.py file.pdf
+import sys
+
+import pypdfium2
+
+document = pypdfium2.PdfDocument(sys.argv[1])
+for page in document:
+    sys.stdout.write(page.get_textpage().get_text_range().replace("\r\n", "\n") + "\n")

data/examples/shaping/extraction_matrix/pdfjs.mjs

@@ -0,0 +1,18 @@
+// The text of a PDF as pdf.js reads it: node pdfjs.mjs path/to/node_modules/pdfjs-dist file.pdf
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+const [root, file] = process.argv.slice(2);
+const { getDocument } = await import(pathToFileURL(join(root, "legacy/build/pdf.mjs")).href);
+const document = await getDocument({
+  data: new Uint8Array(readFileSync(file)),
+  standardFontDataUrl: join(root, "standard_fonts/"),
+  verbosity: 0,
+}).promise;
+
+for (let number = 1; number <= document.numPages; number++) {
+  const page = await document.getPage(number);
+  const content = await page.getTextContent();
+  process.stdout.write(content.items.map((item) => item.str + (item.hasEOL ? "\n" : "")).join("") + "\n");
+}

data/examples/shaping/extraction_matrix/pdfkit.swift

@@ -0,0 +1,6 @@
+// The text of a PDF as PDFKit reads it, which is what Preview copies: swift pdfkit.swift file.pdf
+import Foundation
+import PDFKit
+
+guard let document = PDFDocument(url: URL(fileURLWithPath: CommandLine.arguments[1])) else { exit(1) }
+print(document.string ?? "")

data/examples/shaping/extraction_matrix.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+# What comes out of a PDF whose right-to-left text a shaper placed, extractor
+# by extractor, for three ways of writing it (zoolutions/stationery#151):
+#
+#   A  what the gem writes: a reordered stretch in one Span whose ActualText
+#      is the whole stretch in logical order
+#   B  one Span per cluster, in visual order
+#   C  no Span where the ToUnicode map gives a glyph its text; one per
+#      cluster where it cannot
+#
+# B and C are experiments that live in this file only (Variants, below): the
+# gem writes A. Nothing here is loaded by the gem.
+#
+# Needs, all outside the gem's bundle:
+#
+#   brew install harfbuzz poppler mupdf
+#   gem install harfbuzz-ruby pdf-reader
+#   npm install pdfjs-dist                  (in a directory of its own)
+#   python3 -m venv venv && venv/bin/pip install pypdfium2
+#   NotoSansArabic-Regular.ttf and NotoSansHebrew-Regular.ttf, from
+#   https://github.com/notofonts/notofonts.github.io/tree/main/fonts
+#
+# The Noto Arabic families draw a letter as two glyphs, its shape and its
+# dots, so no ToUnicode map can give their text. Amiri
+# (https://github.com/aliftype/amiri) draws one glyph per letter: run the
+# matrix with both.
+#
+# Run:
+#
+#   ruby -Ilib examples/shaping/extraction_matrix.rb \
+#     --arabic NotoSansArabic-Regular.ttf --hebrew NotoSansHebrew-Regular.ttf \
+#     --out tmp/extraction [--pdfjs dir/node_modules/pdfjs-dist] [--python venv/bin/python]
+#
+# It writes <out>/<variant>-<case>.pdf, the same tagged as PDF/UA-1
+# (<out>/tagged/, for veraPDF), and <out>/matrix.md. An extractor that is not
+# installed is left out of the matrix, never guessed. PDFKit (what Preview
+# reads with) runs on macOS through swift.
+require "optparse"
+require "open3"
+require "fileutils"
+require_relative "harfbuzz_shaper"
+require "stationery/testing/inspector"
+
+module ExtractionMatrix
+  HERE = File.expand_path("extraction_matrix", __dir__)
+  CONTROLS = /[‎‏‪-‮⁦-⁩]/
+
+  # The variant being rendered, :a unless #render says otherwise.
+  def self.variant = Thread.current[:extraction_matrix_variant] || :a
+
+  # The experiments, over Stationery::Fonts::ShapedRun#to_operator.
+  module Variants
+    def to_operator
+      return super if ExtractionMatrix.variant == :a
+
+      groups = pieces.chunk_while { |(left, _), (right, _)| left && right }
+                     .map { |group| [group.first.first, group.flat_map(&:last)] }
+      groups.each_with_index.map do |(plain, indices), index|
+        trailing = index < groups.size - 1
+        plain ? show(indices, trailing) : marked(indices, trailing)
+      end.join("\n")
+    end
+
+    private
+
+    # [[plain, glyph indexes], …], one per cluster in visual order.
+    def pieces
+      counts = glyphs.map(&:cluster).tally
+      own = glyphs.map { |glyph| own?(glyph, counts[glyph.cluster] == 1) }
+      return clusters(glyphs.each_index.to_a, own) if ExtractionMatrix.variant == :c
+
+      # B: the stretches A cuts, each reordered one a Span per cluster.
+      stretches.flat_map { |plain, indices| plain ? [[true, indices]] : clusters(indices, own, spans: true) }
+    end
+
+    def clusters(indices, own, spans: false)
+      indices.chunk_while { |left, right| glyphs[left].cluster == glyphs[right].cluster }
+             .map { |cluster| [!spans && cluster.size == 1 && own[cluster.first], cluster] }
+    end
+  end
+
+  Case = Data.define(:name, :lang, :text, :options)
+
+  CASES = [
+    Case.new("arabic", "ar", "فاتورة ضريبية", { align: :right }),
+    Case.new("hebrew", "he", "שלום עולם", { align: :right }),
+    Case.new("digits", "ar", "فاتورة رقم 2024 بقيمة", { align: :right }),
+    Case.new("marks", "ar", "السَّلَامُ عَلَيْكُمْ", { align: :right }),
+    # A space after the Arabic word would be shaped with it and drawn on its
+    # left, before it: stretches are not reordered (see the README).
+    Case.new("in-latin", "en", "Pay the فاتورة, please.", {}),
+    Case.new("justified", "ar", "هذه فقرة طويلة مكتوبة باللغة العربية لتجربة ضبط السطور من اليمين إلى اليسار " \
+                                "في مستند واحد يحتوي على أكثر من سطر", { align: :justify }),
+    Case.new("wraps", "ar", "مرحبا بالعالم هذه فاتورة ضريبية جديدة من الشركة", { align: :right, size: 20 })
+  ].freeze
+
+  Extractor = Data.define(:name, :command)
+
+  module_function
+
+  def document(kase, fonts)
+    Class.new(Stationery::Document) do
+      page size: [298, 420], margin: 36
+      metadata title: kase.name, lang: kase.lang
+      shaper HarfBuzzShaper.new
+      font_family "Arabic", regular: fonts.fetch(:arabic)
+      font_family "Hebrew", regular: fonts.fetch(:hebrew)
+      font_fallbacks "Arabic", "Hebrew"
+      default_text font: { "ar" => "Arabic", "he" => "Hebrew" }.fetch(kase.lang, "Inter"), size: 14
+      define_method(:view_template) { text kase.text, **kase.options }
+    end
+  end
+
+  def extractors(options)
+    [
+      Extractor.new("poppler (pdftotext)", %w[pdftotext -enc UTF-8 %s -]),
+      Extractor.new("MuPDF (mutool)", %w[mutool draw -q -F txt %s]),
+      Extractor.new("PDFium (pypdfium2)", [options[:python], File.join(HERE, "pdfium.py"), "%s"]),
+      Extractor.new("pdf.js (pdfjs-dist)", ["node", File.join(HERE, "pdfjs.mjs"), options[:pdfjs], "%s"]),
+      Extractor.new("PDFKit (macOS)", ["swift", File.join(HERE, "pdfkit.swift"), "%s"])
+    ].select { |extractor| runs?(extractor) }
+  end
+
+  def runs?(extractor)
+    extractor.command.none?(&:nil?) && system("which", extractor.command.first, out: File::NULL, err: File::NULL)
+  end
+
+  def extract(extractor, path)
+    out, status = Open3.capture2(*extractor.command.map { |part| part == "%s" ? path : part }, err: File::NULL)
+    status.success? ? out.force_encoding(Encoding::UTF_8) : nil
+  end
+
+  def lines(text)
+    text.unicode_normalize(:nfc).split(/[\n\f]+/).map { |line| line.squeeze(" ").strip }.reject(&:empty?)
+  end
+
+  # "as written", "reversed" (every line back to front), or what came out.
+  def verdict(expected, text)
+    return "failed" unless text
+
+    found = lines(text)
+    wanted = expected.unicode_normalize(:nfc)
+    controls = found.join.match?(CONTROLS) ? ", with bidi controls" : ""
+    found = found.map { |line| line.gsub(CONTROLS, "") }
+    return "as written#{controls}" if found.join(" ") == wanted
+    return "reversed#{controls}" if found.map(&:reverse).join(" ") == wanted
+
+    "other#{controls}: `#{found.join(" ⏎ ")}`"
+  end
+
+  def render(options)
+    FileUtils.mkdir_p(File.join(options[:out], "tagged"))
+    %i[a b c].flat_map do |variant|
+      Thread.current[:extraction_matrix_variant] = variant
+      CASES.map do |kase|
+        path = File.join(options[:out], "#{variant}-#{kase.name}.pdf")
+        document(kase, options).new.to_pdf(path)
+        document(kase, options).new.to_pdf(File.join(options[:out], "tagged", File.basename(path)),
+                                           conformance: :pdf_ua1)
+        [variant, kase, path]
+      end
+    end
+  end
+
+  def matrix(options)
+    renders = render(options)
+    readers = extractors(options)
+    rows = renders.map do |variant, kase, path|
+      inspector = Stationery::Testing::Inspector.new(File.binread(path)).text
+      [variant.to_s.upcase, kase.name, verdict(kase.text, inspector)] +
+        readers.map { |reader| verdict(kase.text, extract(reader, path)) }
+    end
+    names = ["Inspector"] + readers.map(&:name)
+    [table(["Variant", "Case", *names], rows), table(["Variant", *names], scores(rows))].join("\n\n")
+  end
+
+  # The cases each reader returns as written, per variant.
+  def scores(rows)
+    rows.group_by(&:first).map do |variant, cases|
+      [variant] + cases.map { |row| row.drop(2) }.transpose.map do |cells|
+        "#{cells.count { |cell| cell.start_with?("as written") }} of #{cells.size}"
+      end
+    end
+  end
+
+  def table(names, rows)
+    ["| #{names.join(" | ")} |", "|#{"---|" * names.size}", *rows.map { |row| "| #{row.join(" | ")} |" }].join("\n")
+  end
+end
+
+Stationery::Fonts::ShapedRun.prepend(ExtractionMatrix::Variants)
+
+if $PROGRAM_NAME == __FILE__
+  options = { out: "tmp/extraction", python: nil, pdfjs: nil }
+  OptionParser.new do |parser|
+    parser.on("--arabic PATH") { |path| options[:arabic] = File.expand_path(path) }
+    parser.on("--hebrew PATH") { |path| options[:hebrew] = File.expand_path(path) }
+    parser.on("--out DIR") { |dir| options[:out] = File.expand_path(dir) }
+    parser.on("--pdfjs DIR") { |dir| options[:pdfjs] = File.expand_path(dir) }
+    parser.on("--python PATH") { |path| options[:python] = File.expand_path(path) }
+  end.parse!
+  abort "usage: see the head of #{__FILE__}" unless options[:arabic] && options[:hebrew]
+
+  table = ExtractionMatrix.matrix(options)
+  File.write(File.join(options[:out], "matrix.md"), "#{table}\n")
+  puts table
+end

data/examples/shaping/harfbuzz_shaper.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+# A shaper for Stationery::Shaper built on HarfBuzz, through the harfbuzz-ruby
+# gem (https://github.com/ydah/harfbuzz, `require "harfbuzz"`). Stationery
+# does not depend on it: copy this file into the application that needs
+# Arabic, Hebrew, Indic or Thai text and add to its Gemfile
+#
+#   gem "harfbuzz-ruby"
+#
+# with the HarfBuzz library installed (`brew install harfbuzz`,
+# `apt-get install libharfbuzz-dev`). Then
+#
+#   class Invoice < Stationery::Document
+#     shaper HarfBuzzShaper.new
+#     font_family "Noto Sans Arabic", regular: "NotoSansArabic-Regular.ttf"
+#   end
+#
+# Run it to write examples/shaping/harfbuzz_shaper.pdf with a font that has
+# the Arabic script:
+#
+#   ruby -Ilib examples/shaping/harfbuzz_shaper.rb NotoSansArabic-Regular.ttf
+#
+# What it does not do: the Unicode bidirectional algorithm. A stretch of text
+# is cut into runs of one direction by its letters alone (digits read left to
+# right, spaces and punctuation go with their neighbours), which places
+# "فاتورة 2024" and "Total: ٤٠ ريال" as a reader expects and gets nested
+# quotations, brackets and explicit embeddings wrong. An application that
+# needs those resolves the levels itself and shapes each run as #shape does.
+require "harfbuzz"
+require "stationery"
+
+class HarfBuzzShaper
+  RIGHT_TO_LEFT = /[\p{Arabic}\p{Hebrew}\p{Syriac}\p{Thaana}\p{Nko}]/
+  STRONG = /[\p{L}\p{Nd}]/
+  Run = Data.define(:direction, :start, :length)
+
+  def initialize
+    @fonts = {}
+    @mutex = Mutex.new
+  end
+
+  # The glyphs of `text` in visual order; see Stationery::Shaper.
+  def call(text, font, features:, language: nil, **)
+    hb_font = font_for(font)
+    switches = HarfBuzz::Feature.from_hash(features)
+    codepoints = text.codepoints
+    runs(text).flat_map { |run| shape(hb_font, codepoints, run, switches, language) }
+  end
+
+  private
+
+  # One HarfBuzz font per font file and face, kept between renders. The
+  # default scale of a HarfBuzz font is its units per em, so what it answers
+  # is in font units, as stationery asks.
+  def font_for(font)
+    @mutex.synchronize do
+      @fonts[[font.path || font.postscript_name, font.index]] ||=
+        HarfBuzz::Font.new(HarfBuzz::Face.new(HarfBuzz::Blob.new(font.data), font.index))
+    end
+  end
+
+  # The whole text is given to HarfBuzz with the run marked in it, so a run
+  # is shaped in its context and the clusters count characters of the text.
+  def shape(font, codepoints, run, features, language)
+    buffer = HarfBuzz::Buffer.new
+    buffer.add_codepoints(codepoints, item_offset: run.start, item_length: run.length)
+    buffer.direction = run.direction
+    buffer.language = HarfBuzz.language(language) if language
+    buffer.guess_segment_properties # the script, from the text
+    HarfBuzz.shape(font, buffer, features)
+    glyphs = []
+    buffer.each_glyph do |gid, cluster, x_advance, _y_advance, x_offset, y_offset|
+      glyphs << Stationery::Shaper::Glyph.new(gid:, cluster:, advance: x_advance, x_offset:, y_offset:)
+    end
+    glyphs
+  end
+
+  # The runs of one direction in visual order: from the right when the first
+  # letter of the text is right to left. Digits do not decide it, so a line
+  # of an Arabic paragraph that starts with a number stays right to left.
+  def runs(text)
+    base = RIGHT_TO_LEFT.match?(text[/\p{L}/].to_s) ? :rtl : :ltr
+    directions = resolve(text.each_char.map { |char| direction_of(char) }, base)
+    start = 0
+    runs = directions.chunk_while { |left, right| left == right }.map do |run|
+      Run.new(run.first, start, run.size).tap { start += run.size }
+    end
+    base == :rtl ? runs.reverse : runs
+  end
+
+  def direction_of(char)
+    return unless STRONG.match?(char)
+
+    RIGHT_TO_LEFT.match?(char) && !char.match?(/\p{Nd}/) ? :rtl : :ltr
+  end
+
+  # Spaces and punctuation take the direction both their neighbours have,
+  # else the base direction.
+  def resolve(directions, base)
+    directions.each_with_index.map do |direction, index|
+      next direction if direction
+
+      before = directions[0...index].compact.last || base
+      after = directions[(index + 1)..].compact.first || base
+      before == after ? before : base
+    end
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  font = ARGV.fetch(0) { abort "usage: ruby -Ilib #{__FILE__} path/to/NotoSansArabic-Regular.ttf" }
+
+  class ExampleShaping < Stationery::Document
+    page size: :a5, margin: 36
+    metadata title: "فاتورة", lang: "ar"
+    shaper HarfBuzzShaper.new
+
+    def view_template
+      text "فاتورة ضريبية", size: 22, align: :right
+      text "مرحبا بالعالم، هذه فاتورة رقم 2024 بقيمة ٤٠ ريال.", size: 14, align: :right
+      text "السَّلَامُ عَلَيْكُمْ", size: 18, align: :right
+    end
+  end
+
+  ExampleShaping.font_family "Arabic", regular: font
+  ExampleShaping.default_text font: "Arabic"
+  out = File.expand_path("harfbuzz_shaper.pdf", __dir__)
+  document = ExampleShaping.new
+  document.to_pdf(out)
+  document.warnings.each { |warning| warn warning.message }
+  puts "wrote #{out}"
+end

data/examples/shaping/rtl_letter.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+# A letter in Arabic, right to left, shaped by HarfBuzz through the shaper
+# hook: joined letters, and numbers kept in reading order inside right-to-left
+# lines. Stationery does not shape text itself, so this one needs what the
+# gem does not ship: the
+# harfbuzz-ruby gem with the HarfBuzz library (see harfbuzz_shaper.rb beside
+# it) and a font with the Arabic script, named by ARABIC_FONT:
+#
+#   gem install harfbuzz-ruby    # with `brew install harfbuzz` or `apt-get install libharfbuzz-dev`
+#   ARABIC_FONT=NotoNaskhArabic-Regular.ttf ruby -Ilib examples/shaping/rtl_letter.rb
+#   ARABIC_FONT=NotoNaskhArabic-Regular.ttf ruby -Ilib exe/stationery render examples/shaping/rtl_letter.rb
+#
+# It is left out of `rake examples`, the docs site and CI, which have neither.
+begin
+  require_relative "harfbuzz_shaper"
+rescue LoadError => e
+  abort "examples/shaping/rtl_letter.rb needs the harfbuzz-ruby gem and the HarfBuzz library " \
+        "(gem install harfbuzz-ruby): #{e.message}"
+end
+require "stationery"
+
+class ExampleRtlLetter < Stationery::Document
+  FONT = ENV.fetch("ARABIC_FONT") do
+    abort "set ARABIC_FONT to a font with the Arabic script, e.g. ARABIC_FONT=NotoNaskhArabic-Regular.ttf"
+  end
+  ACCENT = "#065F46"
+  INK = "#111827"
+  MUTED = "#6B7280"
+
+  page size: :a4, margin: [64, 64, 56, 64]
+  metadata title: "رسالة تأكيد الحجز", author: "Example Travel", lang: "ar", creator: "stationery example"
+
+  # Every stretch of text goes through the shaper, which answers glyphs in
+  # visual order; the Arabic font draws what it has, Inter the rest.
+  shaper HarfBuzzShaper.new
+  font_family "Arabic", regular: FONT
+  font_fallbacks "Inter"
+  default_text font: "Arabic", size: 13, color: INK, align: :right, leading: 6
+
+  footer do
+    rule height: 0.5, color: "#D1D5DB"
+    spacer 6
+    text "Example Travel · booking@travel.example · +971 4 000 0000", size: 9, color: MUTED, align: :center
+  end
+
+  def self.preview
+    new(name: "سارة", booking: "EX-2026-7781", hotel: "فندق الواحة", nights: "٣", total: "٢٤٠٠ درهم")
+  end
+
+  def initialize(name:, booking:, hotel:, nights:, total:)
+    super()
+    @name = name
+    @booking = booking
+    @hotel = hotel
+    @nights = nights
+    @total = total
+  end
+
+  def view_template
+    row(align: :bottom) do
+      column { text "٢٩ سبتمبر ٢٠٢٦", size: 11, color: MUTED, align: :left }
+      column { text "Example Travel", size: 20, color: ACCENT }
+    end
+    spacer 10
+    rule height: 2, color: ACCENT
+    spacer 24
+    text "تأكيد الحجز", size: 22, color: ACCENT
+    spacer 14
+    text "عزيزتي #{@name}،"
+    spacer 8
+    # Arabic with Arabic-Indic digits is one stretch of one font, which the
+    # shaper orders right to left, across as many lines as it takes.
+    text "يسعدنا أن نؤكد حجزك في #{@hotel} لمدة #{@nights} ليالٍ، من ١٢ إلى ١٥ أكتوبر ٢٠٢٦. " \
+         "المبلغ الإجمالي #{@total} شاملاً الضرائب والإفطار. يمكنك إلغاء الحجز مجاناً حتى ٤٨ ساعة قبل الوصول."
+    spacer 14
+    booking
+    spacer 14
+    text "يرجى ذكر رقم الحجز في كل مراسلاتك معنا. نتمنى لك إقامة سعيدة."
+    spacer 30
+    text "مع أطيب التحيات،"
+    text "فريق السفر", color: ACCENT
+  end
+
+  private
+
+  # Latin text drawn from Inter is a stretch of its own, and stretches are
+  # placed left to right in the order written (the hook has no bidi across
+  # fonts): a line that mixes the two directions is built from columns, the
+  # first on the right.
+  def booking
+    box(background: "#ECFDF5", radius: 6, padding: [10, 14]) do
+      row(align: :middle) do
+        column { text @booking, font: "Inter", size: 14, align: :left, color: ACCENT }
+        column { text "رقم الحجز", size: 12, color: MUTED }
+      end
+    end
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  letter = ExampleRtlLetter.preview
+  letter.to_pdf(File.expand_path("rtl_letter.pdf", __dir__))
+  warn letter.warnings.map(&:message) if letter.warnings.any?
+  puts "wrote examples/shaping/rtl_letter.pdf"
+end