stationery 0.8.0 → 0.10.0

data/lib/stationery/html/tree_builder.rb

@@ -1,12 +1,15 @@
 # frozen_string_literal: true
 
+require_relative "css"
 require_relative "tree_builder/blocks"
 
 module Stationery
   module HTML
     # Builds a lenient element tree from tokens, closing what HTML5 closes implicitly (a p before a block,
     # an li before the next li, cells and rows before the next), ignoring stray end tags, then converts
-    # the tree into rich-text blocks.
+    # the tree into rich-text blocks. An element nested deeper than the Rich::Nesting limit is left out
+    # of the tree: what it holds goes to the deepest element kept, so everything that walks the tree
+    # (and the layout it becomes) recurses no deeper than the limit.
     class TreeBuilder
       Element = Data.define(:name, :attributes, :children)
 
@@ -16,6 +19,7 @@ module Stationery
       ].freeze
       HEADINGS = %w[h1 h2 h3 h4 h5 h6].freeze
       SECTIONS = %w[thead tbody tfoot].freeze
+      BLOCKS = (CLOSES_P + SECTIONS + %w[tr td th caption]).freeze
       IMPLIED = {
         "li" => [%w[li], %w[ul ol]],
         "dt" => [%w[dt dd], %w[dl]], "dd" => [%w[dt dd], %w[dl]],
@@ -24,11 +28,21 @@ module Stationery
         "thead" => [SECTIONS, %w[table]], "tbody" => [SECTIONS, %w[table]], "tfoot" => [SECTIONS, %w[table]]
       }.freeze
 
-      def self.parse(tokens) = Blocks.convert(new.build(tokens))
+      # `css` is the Css::Report unsupported styles are told to.
+      def self.parse(tokens, nesting = Rich::Nesting.new, css: nil)
+        builder = new(nesting)
+        root = builder.build(tokens)
+        Blocks.convert(root, Css.parse(builder.sheets, css || Css::Report.new))
+      end
+
+      attr_reader :sheets
 
-      def initialize
+      def initialize(nesting = Rich::Nesting.new)
         @root = Element.new("#root", {}, [])
         @stack = [@root]
+        @nesting = nesting
+        @flattened = [] # the names of the open elements left out of the tree
+        @sheets = []
       end
 
       def build(tokens)
@@ -36,6 +50,7 @@ module Stationery
           case type
           when :start then start(*args)
           when :end then finish(*args)
+          when :style then @sheets << args.first
           else @stack.last.children << args.first
           end
         end
@@ -45,9 +60,13 @@ module Stationery
       private
 
       def start(name, attributes, self_closing)
+        return flatten(name, attributes, self_closing) unless @flattened.empty?
+
         close_nearest(%w[p], %w[table td th caption]) if CLOSES_P.include?(name)
         close_nearest(HEADINGS, []) if HEADINGS.include?(name) && HEADINGS.include?(@stack.last.name)
         close_nearest(*IMPLIED[name]) if IMPLIED.key?(name)
+        return flatten(name, attributes, self_closing) if @stack.size > @nesting.limit
+
         push("tr", {}, false) if %w[td th].include?(name) && %w[table thead tbody tfoot].include?(@stack.last.name)
         push(name, attributes, self_closing)
       end
@@ -58,9 +77,30 @@ module Stationery
         @stack << element unless self_closing
       end
 
+      # Too deep for the tree: a void element (br, img, hr) still takes its place in the deepest
+      # element kept, anything else is only remembered until its end tag, its content going there too.
+      def flatten(name, attributes, self_closing)
+        return push(name, attributes, true) if self_closing
+
+        @flattened << name
+        @nesting.record(@stack.size - 1 + @flattened.size)
+        separate(name)
+      end
+
       def finish(name)
+        flattened = @flattened.rindex(name)
+        return @flattened.slice!(flattened..).each { |left_out| separate(left_out) } if flattened
+
         index = @stack.rindex { |element| element.name == name }
-        @stack.slice!(index..) if index&.positive?
+        return unless index&.positive?
+
+        @stack.slice!(index..)
+        @flattened.clear
+      end
+
+      # A flattened block no longer parts its text from its neighbours'; a space does.
+      def separate(name)
+        @stack.last.children << " " if BLOCKS.include?(name)
       end
 
       def close_nearest(names, boundary)

data/lib/stationery/layout/flow.rb

@@ -21,10 +21,23 @@ module Stationery
 
       def <<(child)
         @children << child
+        @breaks = nil
         forget_measures
         self
       end
 
+      # A flow holding a page break (at any depth) is cut there even when it
+      # would fit on the page it is on.
+      def breaks?
+        @breaks = @children.any? { |child| child.page_break? || child.breaks? } if @breaks.nil?
+        @breaks
+      end
+
+      def leading_break?
+        first = @children.first
+        !first.nil? && (first.page_break? || first.leading_break?)
+      end
+
       def splittable? = true
       def natural_width = @children.map(&:natural_width).max || 0
       def min_width = @children.map(&:min_width).max || 0
@@ -93,6 +106,8 @@ module Stationery
 
           gap = @placed.empty? ? 0 : @flow.gap
           remaining = @height - @used - gap
+          return broken(child, gap, remaining, rest) if child.breaks?
+
           height = child.measure(child.width_in(@width))
           return fits(child, height + gap, remaining - height, rest) if height <= remaining + EPSILON
           return [part(@placed), part(rest)] if child.is_a?(Spacer)
@@ -106,6 +121,20 @@ module Stationery
           [part(@placed), part(rest)]
         end
 
+        # A child holding a page break: what comes before the break stays on
+        # this page, the rest goes to the next, however much room is left. One
+        # that starts with the break goes to the next page whole.
+        def broken(child, gap, remaining, rest)
+          return [part(@placed), part([child, *rest])] if child.leading_break? && !@placed.empty?
+
+          head, tail = child.split(child.width_in(@width), remaining, fresh: @fresh && @placed.empty?)
+          return split_or_move(child, remaining, rest) unless head
+          return [part(@placed + [head]), part([tail, *rest])] if tail
+
+          height = head.measure(head.width_in(@width))
+          fits(head, height + gap, remaining - height, rest)
+        end
+
         def fits(child, consumed, left_after, rest)
           return [part(@placed), part([child, *rest])] if strand?(child, left_after, rest)
 

data/lib/stationery/layout/image.rb

@@ -4,7 +4,8 @@ module Stationery
   module Layout
     # An image sized by width, height, both, or a box to fit into (aspect
     # preserved), never wider than the space it is given. One pixel is one
-    # point when no size is given. `fit: :cover` fills `width:` × `height:`
+    # point when no size is given; a Float width up to 1 is a fraction of the
+    # space (`width: 0.5`), as for boxes and columns. `fit: :cover` fills `width:` × `height:`
     # instead, scaling up and clipping the excess around the centre.
     # `radius:` clips to rounded corners and `rotate:` (degrees, clockwise)
     # turns the painted image around the centre of its rectangle; neither
@@ -25,7 +26,7 @@ module Stationery
         super()
         @tag = alt == false ? nil : Tagging::Element.new(:Figure, alt:, kind: :image)
         @image = source.respond_to?(:build) ? source : Images.load(source)
-        @name = source.is_a?(String) || source.is_a?(Pathname) ? File.basename(source.to_s) : "inline image"
+        @name = name_of(source)
         @max_ppi = max_ppi
         @downscale = downscale
         @width = width
@@ -37,14 +38,16 @@ module Stationery
       end
 
       def size(available)
-        width, height = requested
+        width, height = requested(available)
         return [width, height] if width <= available
 
         [available, height * available / width]
       end
 
       def measure(width) = size(width)[1]
-      def fixed_width(available) = size(available)[0]
+      # A fractional width is a share of the space offered here; measuring and
+      # painting are then given the width that came out of it.
+      def fixed_width(available) = fraction? ? tidy(available * @width) : size(available)[0]
       def natural_width = requested[0]
       def min_width = 0
 
@@ -58,6 +61,14 @@ module Stationery
 
       private
 
+      # What a warning calls the image: the file's name for a path, a
+      # Pathname or an open File (anything with a path), else "inline image".
+      # Asked by duck type: Pathname is not loaded in plain Ruby.
+      def name_of(source)
+        path = source.is_a?(String) ? source : (source.to_path if source.respond_to?(:to_path))
+        path ? File.basename(path) : "inline image"
+      end
+
       def paint_clipped(canvas, x, y, w, h)
         return paint_image(canvas, x, y, w, h) unless @fit == :cover || @radius.positive?
 
@@ -92,19 +103,22 @@ module Stationery
         @image
       end
 
-      def requested
+      def requested(available = nil)
         iw = @image.width.to_f
         ih = @image.height.to_f
+        width = fraction? ? (available || tidy(iw * @width)) : @width
         if @fit.is_a?(Array)
           scale = [@fit[0] / iw, @fit[1] / ih].min
           [iw * scale, ih * scale].map { |v| tidy(v) }
-        elsif @width && @height then [@width, @height]
-        elsif @width then [@width, tidy(ih * @width / iw)]
+        elsif width && @height then [width, @height]
+        elsif width then [width, tidy(ih * width / iw)]
         elsif @height then [tidy(iw * @height / ih), @height]
         else [@image.width, @image.height]
         end
       end
 
+      def fraction? = @width.is_a?(Float) && @width <= 1
+
       def tidy(value) = value.round(6)
     end
   end

data/lib/stationery/layout/mark.rb

@@ -31,6 +31,8 @@ module Stationery
       def fixed_width(available) = @child.fixed_width(available)
       def splittable? = @child.splittable?
       def page_break? = @child.page_break?
+      def breaks? = @child.breaks?
+      def leading_break? = @child.leading_break?
       def avoid_break? = @child.avoid_break?
       def keep_with_next = @child.keep_with_next
 

data/lib/stationery/layout/node.rb

@@ -42,6 +42,10 @@ module Stationery
       # The width this node is laid out at inside a parent of `available`.
       def width_in(available) = fixed_width(available) || available
       def page_break? = false
+      # Whether a page break lies somewhere inside (a flow holding one).
+      def breaks? = false
+      # Whether it starts with a page break (a flow whose first node is one).
+      def leading_break? = false
 
       def split(width, height, **)
         measure(width) <= height + EPSILON ? [self, nil] : [nil, self]

data/lib/stationery/layout/table/cell.rb

@@ -6,6 +6,7 @@ module Stationery
       # One table cell: content (a String, markup String or layout node) and its
       # options, which selections change until the table is laid out.
       class Cell
+        SIDES = %i[top right bottom left].freeze
         TEXT_OPTIONS = { size: :size, color: :color, weight: :weight, style: :style, font: :family,
                          letter_spacing: :letter_spacing }.freeze
 
@@ -103,14 +104,23 @@ module Stationery
           canvas.debug_rect(inner.x, inner.y, inner.width, inner.height, :cell_padding)
         end
 
+        # One path for the cell's border, centred on its edges: the rectangle
+        # when all four sides are drawn, else a line per side.
         def paint_borders(canvas, rect)
           width = @options[:border_width]
           return if width.nil? || width.zero?
 
-          color = @options[:border_color]
-          Array(@options[:borders]).each do |side|
-            x1, y1, x2, y2 = edge(side, rect)
-            canvas.line(x1, y1, x2, y2, color:, width:)
+          sides = Array(@options[:borders]).uniq
+          return if sides.empty?
+
+          canvas.path(stroke: @options[:border_color], line_width: width) do |path|
+            next path.rect(rect.x, rect.y, rect.width, rect.height) if (SIDES - sides).empty?
+
+            sides.each do |side|
+              x1, y1, x2, y2 = edge(side, rect)
+              path.move_to(x1, y1)
+              path.line_to(x2, y2)
+            end
           end
         end
 

data/lib/stationery/layout/table.rb

@@ -6,6 +6,13 @@ module Stationery
     # header rows repeated after a page break, and splitting between rows. A
     # row taller than a fresh page, or any row with split_rows: true, is cut
     # through its cells and continues below the repeated header.
+    #
+    # The fragments a page break cuts a table into keep the whole table's
+    # column metrics, so every page resolves the same column widths, and the
+    # widths and row heights measured for the cut, so a page break measures
+    # nothing again. Laid out at another width they resolve and measure anew.
+    # Where no cell spans rows a cut can fall before any row, so the rows
+    # still to come are not placed on a grid until a page paints them.
     class Table < Node
       DEFAULT_CELL = { padding: 5, borders: %i[top right bottom left], border_width: 0.5,
                        border_color: "#000000" }.freeze
@@ -30,7 +37,7 @@ module Stationery
       end
 
       def row_count = @cells.size
-      def column_count = grid.column_count
+      def column_count = @column_count ||= grid.column_count
       def cell(row, column) = grid.at(row, column)
 
       def rows(spec) = Selection.new(self, Selection.indexes(spec, row_count), (0...column_count).to_a)
@@ -53,6 +60,7 @@ module Stationery
         @column_widths = nil
         @column_metrics = nil
         @row_heights = nil
+        @column_count = nil
         @grid = nil
       end
 
@@ -80,10 +88,11 @@ module Stationery
       def paint(canvas, x, y, width, _height = nil, **)
         widths = column_widths(width)
         heights = row_heights(width)
+        lefts = offsets(widths)
+        tops = offsets(heights)
         canvas.structure(@tag) do
           grid.placements.each do |p|
-            rect = Rect.new(x + widths[0...p.column].sum, y + heights[0...p.row].sum,
-                            widths[p.columns].sum, heights[p.rows].sum)
+            rect = Rect.new(x + lefts[p.column], y + tops[p.row], widths[p.columns].sum, heights[p.rows].sum)
             paint_cell(canvas, p, rect)
           end
         end
@@ -96,14 +105,45 @@ module Stationery
         count += 1 while count < row_count && used + heights[count] <= height + EPSILON && (used += heights[count])
         return [self, nil] if count == row_count
 
-        count = grid.boundaries.grep(@header..count).max
-        split_row(count, width, height - heights.first(count).sum, fresh: options[:fresh]) || split_before(count)
+        count = grid.boundaries.grep(@header..count).max if row_spans?
+        split_row(count, width, height - heights.first(count).sum, fresh: options[:fresh]) ||
+          split_before(count, width)
+      end
+
+      protected
+
+      # Becomes a fragment holding `rows`, with the column widths and row
+      # heights its table measured at `width`.
+      def carry(rows, continued, widths, heights)
+        @cells = rows
+        @continued = continued
+        @grid = nil
+        @column_widths = widths
+        @row_heights = heights
+        self
       end
 
       private
 
       def grid = @grid ||= Grid.new(@cells)
 
+      # Whether any cell spans rows, of the table a fragment was cut from too.
+      def row_spans?
+        return @row_spans if defined?(@row_spans)
+
+        @row_spans = @cells.any? { |row| row.any? { |cell| cell.rowspan > 1 } }
+      end
+
+      # The placements of one row, which no cell from above reaches into.
+      def placements_in(row)
+        return grid.placements.select { |placement| placement.row == row } if row_spans?
+
+        Grid.new([@cells[row]]).placements
+      end
+
+      # Where each column or row starts: the sizes before it, summed.
+      def offsets(sizes) = Array.new(sizes.size) { |index| sizes[0...index].sum }
+
       def paint_cell(canvas, placement, rect)
         cell = placement.cell
         paint = lambda do
@@ -123,28 +163,42 @@ module Stationery
       end
 
       def cell_tag(cell, header)
+        return Tagging::Element.new(:TD) unless header || cell.colspan > 1 || cell.rowspan > 1
+
         attributes = { Scope: (:Column if header), ColSpan: (cell.colspan if cell.colspan > 1),
                        RowSpan: (cell.rowspan if cell.rowspan > 1) }.compact
         Tagging::Element.new(header ? :TH : :TD, attributes: attributes.empty? ? {} : { Table: attributes })
       end
 
-      def split_before(count)
+      def split_before(count, width)
         return [nil, self] if count == @header
 
-        [with_rows(@cells.first(count)), with_rows(@cells.first(@header) + @cells.drop(count), continued: true)]
+        heights = row_heights(width)
+        [fragment(@cells.first(count), width, heights.first(count)),
+         fragment(@cells.first(@header) + @cells.drop(count), width,
+                  heights.first(@header) + heights.drop(count), continued: true)]
       end
 
       def split_row(row, width, space, fresh:)
         return unless @split_rows || (fresh && row == @header)
-        return unless grid.boundaries.include?(row + 1)
+        return if row_spans? && !grid.boundaries.include?(row + 1)
 
         widths = column_widths(width)
-        placements = grid.placements.select { |p| p.row == row }
+        placements = placements_in(row)
         heads, tails = RowSplitter.new(placements, widths:, context: @context).call(space)
         return unless heads
 
-        [with_rows(@cells.first(row) + [heads], widths:),
-         with_rows(@cells.first(@header) + [tails] + @cells.drop(row + 1), widths:, continued: true)]
+        heights = row_heights(width)
+        above, below = [heads, tails].map { |cells| [row_height(placements, cells, widths)] }
+        [fragment(@cells.first(row) + [heads], width, heights.first(row) + above),
+         fragment(@cells.first(@header) + [tails] + @cells.drop(row + 1), width,
+                  heights.first(@header) + below + heights.drop(row + 1), continued: true)]
+      end
+
+      # The height of a cut row's part. No cell of a row that can be cut
+      # spans rows, so it is its tallest cell.
+      def row_height(placements, cells, widths)
+        placements.zip(cells).map { |placement, cell| cell.measure(@context, widths[placement.columns].sum) }.max
       end
 
       def build_cell(content, defaults)
@@ -187,9 +241,13 @@ module Stationery
         @row_heights[width] ||= grid.row_heights(column_widths(width)) { |p, span| p.cell.measure(@context, span) }
       end
 
-      def with_rows(rows, widths: @widths, continued: @continued)
-        self.class.new(rows, context: @context, widths:, width: @width, header: @header, split_rows: @split_rows,
-                             tag: @tag, continued:)
+      # A copy holding other rows of this table. Its cells are built and
+      # tagged already and its column metrics are this table's.
+      def fragment(rows, width, heights, continued: @continued)
+        %i[natural_width min_width].each { |metric| column_metric(metric) }
+        column_count
+        row_spans?
+        dup.carry(rows, continued, { width => column_widths(width) }, { width => heights })
       end
     end
   end

data/lib/stationery/layout/text.rb

@@ -2,21 +2,34 @@
 
 module Stationery
   module Layout
-    # A paragraph of styled runs. Splits between lines.
+    # A paragraph of styled runs. Splits between lines; `orphans:` is the
+    # fewest lines a split leaves at the foot of a page and `widows:` the
+    # fewest it carries to the next (1 and 1: any line). A paragraph that
+    # cannot meet them moves to the next page whole, unless it is already
+    # first on a fresh page, where it splits as best it can.
     class Text < Node
       attr_reader :runs
 
-      def initialize(runs, context:, align: :left, leading: 0, paragraph: nil, tag: Tagging::Element.new(:P))
+      def initialize(runs, context:, align: :left, leading: 0, orphans: 1, widows: 1, paragraph: nil,
+                     tag: Tagging::Element.new(:P))
         super()
         @tag = tag
         @runs = context.book.fallback(runs)
         @context = context
         @align = align
         @leading = leading
+        @orphans = self.class.lines_option(:orphans, orphans)
+        @widows = self.class.lines_option(:widows, widows)
         @paragraph = paragraph
         @paragraphs = {}
       end
 
+      def self.lines_option(name, value)
+        return value if value.is_a?(Integer) && value >= 1
+
+        raise ArgumentError, "#{name}: must be an Integer of at least 1, got #{value.inspect}"
+      end
+
       def splittable? = true
 
       def measure(width) = paragraph(width).height
@@ -25,9 +38,11 @@ module Stationery
         paragraph(width).draw(canvas, x, y, tag: @tag)
       end
 
-      def split(width, height, **)
+      def split(width, height, fresh: false, **)
         head, tail = paragraph(width).split(height)
-        [head && from(head), tail && from(tail)]
+        return [head && from(head), tail && from(tail)] if (@orphans == 1 && @widows == 1) || !(head && tail)
+
+        keep_lines(paragraph(width), head.lines.size, fresh:)
       end
 
       def fit(width, height, overflow:)
@@ -38,19 +53,40 @@ module Stationery
         @natural_width ||= paragraph(Float::INFINITY).lines.map(&:width).max || 0
       end
 
+      # The widest piece that cannot be broken: a word, or one break unit of a
+      # word with CJK characters.
       def min_width
         @min_width ||= @runs.flat_map do |run|
-          style = run.style
-          font = @context.book.resolve(style).first
-          run.text.delete(::Stationery::Text::Wrapper::SOFT_HYPHEN).split(/[ \t\n]+/).map do |word|
-            font.width_of(word, style.render_size, letter_spacing: style.letter_spacing, kerning: style.kerning,
-                                                   ligatures: style.ligatures, features: style.features)
+          font = @context.book.resolve(run.style).first
+          run.text.delete(::Stationery::Text::Wrapper::SOFT_HYPHEN).split(/[ \t\n\u200B]+/).map do |word|
+            next piece_width(font, run.style, word) unless ::Stationery::Text::Breaks.cjk?(word)
+
+            ::Stationery::Text::Breaks.units(word).map { |unit, _| piece_width(font, run.style, unit) }.max
           end
         end.max || 0
       end
 
       private
 
+      # Applies orphans and widows to a split after `fitting` lines: carries
+      # more lines over for the widows, then moves the paragraph whole when
+      # too few would stay. First on a fresh page nothing can move, so the
+      # widows are honoured if a line can still stay and the orphans are not.
+      def keep_lines(paragraph, fitting, fresh:)
+        total = paragraph.lines.size
+        kept = [fitting, total - @widows].min
+        kept = fitting if fresh && kept < 1
+        return [nil, self] if !fresh && (kept < @orphans || total < @orphans + @widows)
+
+        head, tail = paragraph.split_at(kept)
+        [head && from(head), tail && from(tail)]
+      end
+
+      def piece_width(font, style, text)
+        font.width_of(text, style.render_size, letter_spacing: style.letter_spacing, kerning: style.kerning,
+                                               ligatures: style.ligatures, features: style.features)
+      end
+
       def paragraph(width)
         @paragraph || (@paragraphs[width] ||= ::Stationery::Text::Paragraph.new(
           @runs, book: @context.book, width:, align: @align, leading: @leading, fallback_style: @context.style
@@ -58,7 +94,8 @@ module Stationery
       end
 
       def from(paragraph)
-        self.class.new(@runs, context: @context, align: @align, leading: @leading, paragraph:, tag: @tag)
+        self.class.new(@runs, context: @context, align: @align, leading: @leading, orphans: @orphans, widows: @widows,
+                              paragraph:, tag: @tag)
       end
     end
   end

data/lib/stationery/markdown/block_parser/containers.rb

@@ -9,9 +9,30 @@ module Stationery
       module Containers
         QUOTE = /\A {0,3}> ?/
         LIST = /\A(?<indent> {0,3})(?<marker>[-+*]|(?<number>\d{1,9})[.)])(?<space> *)(?<rest>.*)\z/
+        MARKER = /\G[ \t]*(?:>|(?:[-+*]|\d{1,9}[.)])(?=[ \t]|\z))/
 
         private
 
+        def container?(line) = QUOTE.match?(line) || !list_marker(line).nil?
+
+        # Block quotes and lists nested past the limit: their lines, up to a blank one, as one
+        # paragraph with the markers dropped.
+        def flattened
+          lines = []
+          while (line = @lines[@index]) && !blank?(line)
+            lines << unmarked(line)
+            @index += 1
+          end
+          lines.reject!(&:empty?)
+          Rich::Paragraph.new(inlines: text(lines)) if lines.any?
+        end
+
+        def unmarked(line)
+          markers = line.scan(MARKER).size
+          @nesting.record(@depth + markers)
+          line.sub(/\A(?:#{MARKER.source.delete_prefix("\\G")})*[ \t]*/, "")
+        end
+
         def blockquote
           lines = []
           while (line = @lines[@index])

data/lib/stationery/markdown/block_parser.rb

@@ -10,6 +10,8 @@ module Stationery
     # Splits CommonMark source into blocks, line by line. Paragraph, heading and table cell text is left
     # raw (a String in place of inlines) for Markdown.parse to run through the inline parser once every
     # link reference definition, which this parser collects into `refs`, is known. Raw HTML stays text.
+    # Every block quote and list is parsed by a parser of its own, one level deeper; at the
+    # Rich::Nesting limit a further one becomes a paragraph of its text instead.
     class BlockParser
       include Containers
       include Tables
@@ -24,7 +26,7 @@ module Stationery
         (?:[ \t]+(?:"[^"]*"|'[^']*'|\([^)]*\)))?[ \t]*\z
       /x
 
-      def self.parse(source, refs) = new(lines(source), refs).blocks
+      def self.parse(source, refs, nesting = Rich::Nesting.new) = new(lines(source), refs, nesting).blocks
 
       def self.lines(source) = source.to_s.split(/\r\n?|\n/).map { |line| expand_tabs(line) }
 
@@ -39,9 +41,12 @@ module Stationery
         expanded + line[prefix.length..]
       end
 
-      def initialize(lines, refs)
+      # `depth` counts the block quotes and lists this parser is inside.
+      def initialize(lines, refs, nesting = Rich::Nesting.new, depth = 0)
         @lines = lines
         @refs = refs
+        @nesting = nesting
+        @depth = depth
         @index = 0
       end
 
@@ -62,6 +67,7 @@ module Stationery
         elsif (match = FENCE.match(line)) then fenced_code(match)
         elsif (match = ATX.match(line)) then atx(match)
         elsif THEMATIC.match?(line) then skip(Rich::Rule.new)
+        elsif container?(line) && @depth >= @nesting.limit then flattened
         elsif QUOTE.match?(line) then blockquote
         elsif (match = list_marker(line)) then list(match)
         elsif table_start? then table
@@ -135,7 +141,7 @@ module Stationery
 
       def blank?(line) = line.strip.empty?
       def indent(line) = line[/\A */].length
-      def nested(lines) = BlockParser.new(lines, @refs).blocks
+      def nested(lines) = BlockParser.new(lines, @refs, @nesting, @depth + 1).blocks
     end
   end
 end

data/lib/stationery/markdown/document.rb

@@ -1,15 +1,21 @@
 # frozen_string_literal: true
 
+require_relative "../rich/nesting"
 require_relative "block_parser"
 require_relative "inline_parser"
 
 module Stationery
   # A CommonMark subset (plus GFM tables and strikethrough) to rich-text blocks (see Stationery::Rich).
   module Markdown
-    def self.parse(source)
+    # Block quotes and lists nested deeper than `max_depth` are flattened into
+    # a paragraph; the block is then given how deep the source went.
+    def self.parse(source, max_depth: Rich::Nesting::DEFAULT)
+      nesting = Rich::Nesting.new(max_depth)
       Stationery.instrument("parse.stationery", format: :markdown, bytes: source.bytesize) do
         refs = {}
-        Resolver.new(refs).blocks(BlockParser.parse(source, refs))
+        Resolver.new(refs).blocks(BlockParser.parse(source, refs, nesting)).tap do
+          yield nesting.deepest if nesting.exceeded? && block_given?
+        end
       end
     end