bandoola 0.1.0

data/lib/bandoola/view/element.rb

@@ -0,0 +1,431 @@
+module Bandoola
+  class View
+    # The base node in the document tree. Subclasses describe a kind of
+    # content (Div, Text, Img); the layout and paint machinery here is shared
+    # so a new element only has to say how tall it is and how to draw itself.
+    #
+    # Geometry is in PDF user space (origin bottom-left, y increasing up).
+    # +x+/+top+ are the top-left corner of the element's border box and
+    # +w+/+h+ its size; they're filled in during #layout.
+    #
+    # Elements flow like HTML blocks: by default each fills its container's
+    # content width and stacks below the previous one with no gap. A width
+    # (w-1/2, w-32, …) shrinks an element so siblings can share a row; when
+    # the next element no longer fits, the flow reflows onto a new row. Height
+    # is the content's natural height unless a class fixes it (h-16, h-1/2).
+    # Padding insets an element's children; margin spaces it from neighbours.
+    class Element
+      EPSILON = 0.01
+
+      # The cubic-Bézier control-point ratio that approximates a quarter
+      # circle (4/3 * (sqrt(2) - 1)), used to round box corners.
+      KAPPA = 0.5522847498
+
+      attr_reader :style, :children
+      attr_accessor :x, :top, :w, :h
+
+      def initialize(style)
+        @style = style
+        @children = []
+      end
+
+      # Position this element's border box and lay out its contents, setting
+      # +h+. A width is handed down by the parent's flow; the height is either
+      # fixed by a class or grows to fit the content. +avail_height+ is the
+      # content-height budget the parent offers, used to resolve h-fractions.
+      def layout(origin_x, top, width, avail_height, typeset = PLAIN_TYPESET)
+        @x = origin_x
+        @top = top
+        @w = width
+
+        pad = style.padding
+        fixed = resolved_height(avail_height)
+        budget = (fixed || avail_height) - pad.top - pad.bottom
+        inner = content_height(origin_x + pad.left, top - pad.top, width - pad.left - pad.right, budget, typeset)
+        @h = fixed || (pad.top + inner + pad.bottom)
+      end
+
+      # Lay out any children and return the height the content occupies. +typeset+
+      # carries the inherited font and a text measurer for wrapping. The default
+      # is container behavior (flow children); leaf elements such as Text and
+      # Img override this with their own intrinsic height.
+      def content_height(left, top, avail, avail_height, typeset)
+        flow(left, top, avail, avail_height, typeset)
+      end
+
+      # Append this element's drawing instructions to +buffer+. +resources+
+      # collects fonts and image XObjects for the serializer; +font+ and
+      # +weight+ are inherited from ancestors. The default is a container that
+      # paints its children, passing the inherited typography down.
+      def paint(buffer, resources, font = "sans", weight = NORMAL_WEIGHT)
+        children.each { |child| child.paint(buffer, resources, font, weight) }
+      end
+
+      # Shift this element and its descendants vertically by +delta+ points. Used
+      # to move a page's worth of body content up to the top of its page.
+      def offset(delta)
+        @top += delta
+        children.each { |child| child.offset(delta) }
+      end
+
+      # The element's outer (margin-box) width within +avail+: its fixed width
+      # plus margins, a fraction of +avail+, or the whole of +avail+. Public
+      # because a parent's #flow asks each child for it.
+      def outer_width(avail)
+        margin = style.margin
+        return style.width + margin.left + margin.right if style.width
+
+        if style.width_fraction
+          numerator, denominator = style.width_fraction
+          return avail * numerator / denominator.to_f
+        end
+
+        avail
+      end
+
+      protected
+
+      def coord(value)
+        format("%.2f", value).sub(/\.?0+\z/, "")
+      end
+
+      # Format a color channel (0..1) for the rg/RG operators.
+      def channel(value)
+        format("%.3f", value).sub(/\.?0+\z/, "")
+      end
+
+      # A color operator from an [r, g, b] triple. +operator+ is rg for the
+      # nonstroking (fill) color or RG for the stroking color.
+      def color_op(rgb, operator = "rg")
+        red, green, blue = rgb
+        "#{channel(red)} #{channel(green)} #{channel(blue)} #{operator}\n"
+      end
+
+      private
+
+      # An explicit border-box height from a class (fixed or a fraction of the
+      # available height), or nil to grow with the content.
+      def resolved_height(avail_height)
+        return style.height if style.height
+
+        if style.height_fraction
+          numerator, denominator = style.height_fraction
+          return avail_height * numerator / denominator.to_f
+        end
+
+        nil
+      end
+
+      # Flow children left-to-right within the content box, wrapping to a new
+      # row when the next child would overflow. Returns the total height.
+      def flow(left, top, avail, avail_height, typeset)
+        cursor_x = left
+        row_top = top
+        row_height = 0
+        stacked = 0
+
+        children.each do |child|
+          margin = child.style.margin
+          outer = child.outer_width(avail)
+
+          if cursor_x > left && (cursor_x - left) + outer > avail + EPSILON
+            stacked += row_height
+            row_top -= row_height
+            cursor_x = left
+            row_height = 0
+          end
+
+          child.layout(cursor_x + margin.left, row_top - margin.top,
+                       outer - margin.left - margin.right, avail_height, typeset)
+          outer_height = margin.top + child.h + margin.bottom
+          row_height = outer_height if outer_height > row_height
+          cursor_x += outer
+        end
+
+        stacked + row_height
+      end
+
+      # Clamp a requested radius so it never exceeds half the box (which is
+      # what turns rounded-full into a pill/circle).
+      def clamp_radius(radius, width, height)
+        [radius.to_f, width / 2.0, height / 2.0].min
+      end
+
+      # A rounded rectangle as PDF path operators: straight edges joined by
+      # quarter-circle corners, each a cubic Bézier whose control points sit
+      # KAPPA of the radius from the corner. (left, bottom) is the lower-left.
+      def rounded_path(left, bottom, width, height, radius)
+        right = left + width
+        top_edge = bottom + height
+        inset = radius - (radius * KAPPA)
+        [
+          "#{point([left + radius, bottom])} m",
+          "#{point([right - radius, bottom])} l",
+          corner([right - inset, bottom], [right, bottom + inset], [right, bottom + radius]),
+          "#{point([right, top_edge - radius])} l",
+          corner([right, top_edge - inset], [right - inset, top_edge], [right - radius, top_edge]),
+          "#{point([left + radius, top_edge])} l",
+          corner([left + inset, top_edge], [left, top_edge - inset], [left, top_edge - radius]),
+          "#{point([left, bottom + radius])} l",
+          corner([left, bottom + inset], [left + inset, bottom], [left + radius, bottom]),
+          "h"
+        ].join("\n")
+      end
+
+      def corner(control1, control2, endpoint)
+        "#{point(control1)} #{point(control2)} #{point(endpoint)} c"
+      end
+
+      def point(coords)
+        "#{coord(coords[0])} #{coord(coords[1])}"
+      end
+    end
+
+    # A box that wraps whatever its block draws. It is invisible by default; a
+    # bg-<color>-<shade> class fills it and a border-N class strokes it (in
+    # border-<color>-<shade> if given, otherwise black).
+    class Div < Element
+      def paint(buffer, resources, font = "sans", weight = NORMAL_WEIGHT)
+        paint_background(buffer) if style.background
+        paint_border(buffer) if style.border
+        # Children inherit this div's font/weight classes if it set them.
+        super(buffer, resources, style.font || font, style.font_weight || weight)
+      end
+
+      # Children also inherit the div's font/weight when wrapping, so they
+      # measure against the right metrics.
+      def content_height(left, top, avail, avail_height, typeset)
+        flow(left, top, avail, avail_height, typeset.inherit(style))
+      end
+
+      private
+
+      def paint_background(buffer)
+        fill(buffer, style.background, "rg", "f")
+      end
+
+      # A uniform border (every side the same width — the bare `border` and
+      # border-N classes) strokes the whole box outline, so it still follows a
+      # rounded-* radius. A mixed/partial border (border-b, border-x-2, …)
+      # strokes only the requested edges as straight line segments; those
+      # ignore any corner radius.
+      def paint_border(buffer)
+        sides = style.border
+        if uniform_border?(sides)
+          line_width = "#{sides[:top]} w\n"
+          fill(buffer, border_color, "RG", "S", line_width)
+        else
+          paint_border_sides(buffer, sides)
+        end
+      end
+
+      def uniform_border?(sides)
+        widths = sides.values
+        widths.all?(&:positive?) && widths.uniq.size == 1
+      end
+
+      def paint_border_sides(buffer, sides)
+        bottom = top - h
+        right = x + w
+        stroke_edge(buffer, sides[:top], [x, top], [right, top]) if sides[:top].positive?
+        stroke_edge(buffer, sides[:bottom], [x, bottom], [right, bottom]) if sides[:bottom].positive?
+        stroke_edge(buffer, sides[:left], [x, top], [x, bottom]) if sides[:left].positive?
+        stroke_edge(buffer, sides[:right], [right, top], [right, bottom]) if sides[:right].positive?
+      end
+
+      def stroke_edge(buffer, width, from, to)
+        red, green, blue = border_color
+        buffer << "q\n#{width} w\n#{channel(red)} #{channel(green)} #{channel(blue)} RG\n" \
+                  "#{coord(from[0])} #{coord(from[1])} m\n#{coord(to[0])} #{coord(to[1])} l\nS\nQ\n"
+      end
+
+      def border_color
+        style.border_color || [0.0, 0.0, 0.0]
+      end
+
+      # Draw this box's shape with the given color. +set+ is the color
+      # operator (rg fill / RG stroke), +paint_op+ is f or S, and +prefix+ is
+      # any extra setup (e.g. line width). q/Q isolates the graphics state.
+      def fill(buffer, color, set, paint_op, prefix = "")
+        red, green, blue = color
+        buffer << "q\n#{prefix}#{channel(red)} #{channel(green)} #{channel(blue)} #{set}\n" \
+                  "#{box_path}\n#{paint_op}\nQ\n"
+      end
+
+      # The box outline as PDF path operators: a plain rectangle, or — when a
+      # rounded-* class set a radius — a rectangle with Bézier corners.
+      def box_path
+        bottom = top - h
+        radius = style.radius ? clamp_radius(style.radius, w, h) : 0.0
+        return "#{coord(x)} #{coord(bottom)} #{coord(w)} #{coord(h)} re" unless radius.positive?
+
+        rounded_path(x, bottom, w, h, radius)
+      end
+    end
+
+    # A run of text. Embedded newlines become separate lines; there is no word
+    # wrapping yet, so a long line can extend past its box.
+    class Text < Element
+      # Faux-bold stroke per 100 weight steps above normal, as a fraction of
+      # the font size. Tuned so font-bold (700) reads clearly bold.
+      BOLD_STEP = 0.008
+
+      attr_reader :content
+
+      def initialize(style, content)
+        super(style)
+        @content = content
+      end
+
+      # Wrap the text to the available width (using +typeset+'s measurer and the
+      # effective font), storing the lines for paint, and return their height.
+      def content_height(_left, _top, avail, _avail_height, typeset)
+        @lines = wrap(avail, typeset)
+        @lines.length * line_height
+      end
+
+      def paint(buffer, resources, font = "sans", weight = NORMAL_WEIGHT)
+        pad = style.padding
+        left = x + pad.left
+        content_top = top - pad.top
+        content_width = w - pad.left - pad.right
+        # The text's own font-*/weight classes win over the inherited ones.
+        name, native, face = resources.font(style.font || font, style.font_weight || weight)
+        # Synthesise only the weight the chosen face doesn't already provide.
+        setup = text_state((style.font_weight || weight) - native)
+
+        buffer << "q\n#{setup}" if setup
+        wrapped.each_with_index do |line, index|
+          baseline = content_top - font_size - (index * line_height)
+          indent = align_indent(line, content_width, face)
+          # The font encodes the text (WinAnsi literal or Identity-H glyph ids).
+          buffer << "BT\n/#{name} #{font_size} Tf\n" \
+                    "#{coord(left + indent)} #{coord(baseline)} Td\n#{face.encode(line)} Tj\nET\n"
+        end
+        buffer << "Q\n" if setup
+      end
+
+      private
+
+      # Horizontal offset for a line under the text-align class: 0 for the
+      # default left, the leftover width for right, half of it for center.
+      def align_indent(line, content_width, face)
+        return 0.0 if style.text_align.nil? || style.text_align == :left
+
+        slack = content_width - face.width_of(line, font_size)
+        style.text_align == :center ? slack / 2.0 : slack
+      end
+
+      # The lines decided during layout; falls back to hard line breaks only if
+      # painted without a prior layout.
+      def wrapped
+        @lines || content.split("\n", -1)
+      end
+
+      # Break the content into lines that fit +avail+ points wide. With no
+      # measurer (e.g. a layout without typesetting) only hard newlines break.
+      def wrap(avail, typeset)
+        return content.split("\n", -1) unless typeset.measure
+
+        family = style.font || typeset.font
+        weight = style.font_weight || typeset.weight
+        fits = ->(text) { typeset.measure.call(text, family, weight, font_size) <= avail }
+        content.split("\n", -1).flat_map { |paragraph| wrap_paragraph(paragraph, fits) }
+      end
+
+      # Greedy word wrap: keep adding words while they fit; a word too wide to
+      # fit alone gets its own (overflowing) line.
+      def wrap_paragraph(paragraph, fits)
+        words = paragraph.split
+        return [paragraph] if words.empty?
+
+        lines = []
+        current = nil
+        words.each do |word|
+          candidate = current ? "#{current} #{word}" : word
+          if current.nil? || fits.call(candidate)
+            current = candidate
+          else
+            lines << current
+            current = word
+          end
+        end
+        lines << current
+        lines
+      end
+
+      # Font size from a text-<size> class, else the page default. Size affects
+      # layout (it sets the line height), so it is per-text rather than
+      # inherited like font/weight.
+      def font_size
+        style.text_size || FONT_SIZE
+      end
+
+      # Line height scaled from the default proportion (LINE_HEIGHT for the
+      # default FONT_SIZE).
+      def line_height
+        (font_size * LINE_HEIGHT / FONT_SIZE.to_f).round
+      end
+
+      # The graphics-state setup for a text run: a fill color (text-<color>)
+      # and, when +extra_weight+ remains beyond the chosen face, a matching
+      # stroke that thickens the glyphs (render mode 2 = fill + stroke).
+      # Returns nil when neither applies, so plain black text needs no wrapper.
+      def text_state(extra_weight)
+        stroke = faux_bold_width(extra_weight)
+        color = style.text_color
+        return nil unless color || stroke.positive?
+
+        color ||= [0.0, 0.0, 0.0]
+        setup = color_op(color)
+        setup += "#{color_op(color, "RG")}#{coord(stroke)} w\n2 Tr\n" if stroke.positive?
+        setup
+      end
+
+      def faux_bold_width(extra_weight)
+        return 0.0 if extra_weight <= 0
+
+        extra_weight / 100.0 * font_size * BOLD_STEP
+      end
+    end
+
+    # An image element. +image+ is an already-loaded Svg (drawn inline) or Jpeg
+    # (embedded as an XObject); View loads and caches it. With no width class it
+    # takes the image's intrinsic width; height defaults to the aspect-preserving
+    # value unless a height class overrides it.
+    class Img < Element
+      def initialize(style, image)
+        super(style)
+        @image = image
+      end
+
+      def content_height(_left, _top, avail, _avail_height, _typeset)
+        avail / @image.aspect
+      end
+
+      def paint(buffer, resources, _font = "sans", _weight = NORMAL_WEIGHT)
+        pad = style.padding
+        left = x + pad.left
+        box_top = top - pad.top
+        width = w - pad.left - pad.right
+        height = h - pad.top - pad.bottom
+        box = [left, box_top, width, height]
+        radius = style.radius ? clamp_radius(style.radius, width, height) : 0.0
+
+        return @image.paint_into(buffer, resources, box) unless radius.positive?
+
+        # Clip the image to a rounded rectangle: build the path, set it as the
+        # clip region with `W n`, draw the image inside, then restore.
+        buffer << "q\n#{rounded_path(left, box_top - height, width, height, radius)}\nW n\n"
+        @image.paint_into(buffer, resources, box)
+        buffer << "Q\n"
+      end
+
+      def outer_width(avail)
+        return super if style.width || style.width_fraction
+
+        @image.intrinsic_width + style.margin.left + style.margin.right
+      end
+    end
+  end
+end

data/lib/bandoola/view/file.rb

@@ -0,0 +1,16 @@
+module Bandoola
+  class View
+    # Persisting a rendered document to disk.
+    #
+    # Mixed into View; #write reads the View instance's #contents. Named
+    # Writer rather than File so it never shadows Ruby's ::File for code in a
+    # View subclass body.
+    module Writer
+      # Write the most recently rendered contents to +path+. Returns self.
+      def write(path)
+        File.binwrite(path, contents)
+        self
+      end
+    end
+  end
+end

data/lib/bandoola/view/header.rb

@@ -0,0 +1,110 @@
+module Bandoola
+  class View
+    # The PDF document structure that wraps the rendered page buffers: the file
+    # header, the numbered objects (catalog, pages, one Page and content stream
+    # per page, then the fonts and image XObjects used), the cross-reference
+    # table of their byte offsets, and the trailer pointing at the root.
+    #
+    # The shared MediaBox and /Resources sit on the Pages node and are inherited
+    # by every page, so they're declared once however many pages there are.
+    #
+    # Mixed into View; its methods run against the View instance, so they can
+    # read @page_buffers, @resources and the geometry methods on the class.
+    module Header
+      private
+
+      # Wrap @page_buffers in PDF structure and return the file as bytes. Built
+      # in binary, since embedded fonts and images carry raw bytes.
+      def serialize
+        objects = build_objects
+
+        out = String.new("%PDF-1.4\n", encoding: Encoding::ASCII_8BIT)
+        # A binary comment marks the file as containing 8-bit data, which
+        # keeps naive tools from mangling it as plain text.
+        out << "%\xE2\xE3\xCF\xD3\n".b
+
+        offsets = []
+        objects.each_with_index do |body, index|
+          offsets << out.bytesize
+          # body.b keeps text bytes (which may be non-ASCII) and binary font/
+          # image bytes alike from clashing with the buffer's encoding.
+          out << "#{index + 1} 0 obj\n" << body.b << "\nendobj\n"
+        end
+
+        xref_offset = out.bytesize
+        out << build_xref(offsets)
+        out << build_trailer(objects.size, xref_offset)
+        out
+      end
+
+      # The document's objects, in order: catalog (1), pages (2), the N Page
+      # objects, the N content streams, then a block per used font and one
+      # XObject per used image. Object numbers are 1-based array positions.
+      def build_objects
+        pages = @page_buffers.size
+        first_page = 3
+        first_content = first_page + pages
+        number = first_content + pages
+
+        extras = []
+        font_refs = {}
+        @resources.fonts.each do |name, font|
+          font_refs[name] = number
+          extras.concat(font.pdf_objects(number))
+          number += font.object_count
+        end
+        image_refs = {}
+        @resources.images.each do |name, image|
+          image_refs[name] = number
+          extras << image.xobject
+          number += 1
+        end
+
+        page_objects = Array.new(pages) { |i| page_object(first_content + i) }
+        content_objects = @page_buffers.map { |buffer| content_object(buffer) }
+
+        [catalog, pages_object(first_page, pages, font_refs, image_refs), *page_objects, *content_objects, *extras]
+      end
+
+      def catalog
+        "<< /Type /Catalog /Pages 2 0 R >>"
+      end
+
+      # The Pages node holds the kid list and the inherited MediaBox/Resources.
+      def pages_object(first_page, count, font_refs, image_refs)
+        kids = (first_page...(first_page + count)).map { |n| "#{n} 0 R" }.join(" ")
+        resources = "/Font << #{refs(font_refs)} >>"
+        resources += " /XObject << #{refs(image_refs)} >>" unless image_refs.empty?
+        "<< /Type /Pages /Kids [#{kids}] /Count #{count} " \
+          "/MediaBox [0 0 #{width} #{height}] /Resources << #{resources} >> >>"
+      end
+
+      def page_object(content_number)
+        "<< /Type /Page /Parent 2 0 R /Contents #{content_number} 0 R >>"
+      end
+
+      def content_object(buffer)
+        "<< /Length #{buffer.bytesize} >>\nstream\n#{buffer}\nendstream"
+      end
+
+      def refs(name_to_number)
+        name_to_number.map { |name, number| "/#{name} #{number} 0 R" }.join(" ")
+      end
+
+      def build_xref(offsets)
+        # The table opens with a free entry for object 0, then one
+        # fixed-width line per object giving its byte offset.
+        rows = +"0000000000 65535 f \n"
+        offsets.each do |offset|
+          rows << format("%010d 00000 n \n", offset)
+        end
+        "xref\n0 #{offsets.size + 1}\n#{rows}"
+      end
+
+      def build_trailer(object_count, xref_offset)
+        "trailer\n<< /Size #{object_count + 1} /Root 1 0 R >>\n" \
+          "startxref\n#{xref_offset}\n%%EOF\n"
+      end
+    end
+  end
+end

data/lib/bandoola/view/resources.rb

@@ -0,0 +1,44 @@
+module Bandoola
+  class View
+    # Collects the fonts and image XObjects referenced by the content stream
+    # during the paint pass, so the serializer can emit them as objects and
+    # list them in the page's /Resources. Each gets a name used by the content
+    # stream: F1, F2, … for fonts (the Tf operator) and Im1, Im2, … for images
+    # (the Do operator).
+    #
+    # Fonts are resolved lazily through +font_resolver+ (a callable name ->
+    # Font), so a font registered but never used costs nothing.
+    class Resources
+      def initialize(font_resolver)
+        @font_resolver = font_resolver
+        @fonts = {}  # face key => [resource_name, font]
+        @images = {} # image => [resource_name, image]
+      end
+
+      # The used fonts/images as [resource_name, …] pairs, in first-use order.
+      def fonts
+        @fonts.values
+      end
+
+      def images
+        @images.values
+      end
+
+      # Resolve a (family, weight) to a face and return [resource_name,
+      # native_weight, font]. Faces are deduped by the resolver's cache key, so
+      # two weights of one family share a resource only if they map to one file.
+      def font(family, weight)
+        key, font, native = @font_resolver.call(family, weight)
+        entry = (@fonts[key] ||= ["F#{@fonts.size + 1}", font])
+        [entry[0], native, font]
+      end
+
+      # Resource name for an image, deduped so the same image painted more than
+      # once (e.g. a logo in a header repeated on every page) embeds once.
+      def add_image(image)
+        entry = (@images[image] ||= ["Im#{@images.size + 1}", image])
+        entry[0]
+      end
+    end
+  end
+end

data/lib/bandoola/view/style/borders.rb

@@ -0,0 +1,66 @@
+module Bandoola
+  class View
+    class Style
+      # Border widths and corner radius. `border` and `border-N` (border-1 …
+      # border-16) set a stroke width in points on every side; the directional
+      # classes set a subset — -t/-r/-b/-l one edge, -x left+right, -y
+      # top+bottom — each optionally with a width (`border-b-2`) and defaulting
+      # to 1pt. The rounded-* classes set a corner radius, also in points
+      # (Tailwind's scale, 1px ≈ 1pt). Border color lives in Colors;
+      # border-<color>-<shade> has a word between the dashes, so it never
+      # collides with these. Mixed into Style.
+      module Borders
+        # border / border-2 / border-b / border-t-4 / border-x-2.
+        BORDER = /\Aborder(?:-([xytrbl]))?(?:-(\d+))?\z/
+        WIDTHS = (1..16)
+
+        # Which edges each directional suffix paints (nil = bare/numeric form).
+        SIDES = {
+          nil => %i[top right bottom left],
+          "t" => %i[top], "r" => %i[right], "b" => %i[bottom], "l" => %i[left],
+          "x" => %i[left right], "y" => %i[top bottom]
+        }.freeze
+
+        # Tailwind's border-radius scale, in points. rounded-full uses a large
+        # value the renderer clamps to half the box (a pill / circle).
+        RADII = {
+          "rounded-none" => 0,
+          "rounded-sm" => 2,
+          "rounded" => 4,
+          "rounded-md" => 6,
+          "rounded-lg" => 8,
+          "rounded-xl" => 12,
+          "rounded-2xl" => 16,
+          "rounded-3xl" => 24,
+          "rounded-full" => 9999
+        }.freeze
+
+        attr_reader :border, :radius
+
+        def init_borders
+          @border = nil # {top:, right:, bottom:, left:} widths in points, or nil
+          @radius = nil # corner radius in points, or nil for square corners
+        end
+
+        def apply_border_token(token)
+          if (match = token.match(BORDER))
+            apply_border_width(match[1], match[2])
+          elsif RADII.key?(token)
+            @radius = RADII[token]
+          end
+        end
+
+        # Set +width+ (defaulting to 1pt) on the edges named by +side+, lazily
+        # allocating the per-side hash so a div with no border classes keeps a
+        # nil border.
+        def apply_border_width(side, width)
+          width = width ? width.to_i : 1
+          return unless WIDTHS.include?(width)
+
+          @border ||= { top: 0, right: 0, bottom: 0, left: 0 }
+          SIDES.fetch(side).each { |edge| @border[edge] = width }
+        end
+      end
+    end
+  end
+end