From a006f79c943672e2099257780f7d601b2da084a4 Mon Sep 17 00:00:00 2001
From: Jaro <jaro@argonaut-constellation.org>
Date: Wed, 22 Feb 2023 17:03:01 +0100
Subject: [PATCH] Use CSS3 terminology for fragments and containing block.

---
 src/Data/Text/ParagraphLayout/Plain.hs | 46 +++++++++++++++-----------
 1 file changed, 26 insertions(+), 20 deletions(-)

diff --git a/src/Data/Text/ParagraphLayout/Plain.hs b/src/Data/Text/ParagraphLayout/Plain.hs
index 3a0cd7e..ad49e86 100644
--- a/src/Data/Text/ParagraphLayout/Plain.hs
+++ b/src/Data/Text/ParagraphLayout/Plain.hs
@@ -81,20 +81,26 @@ data LineHeight
 -- | The resulting layout of the whole paragraph.
 data ParagraphLayout = ParagraphLayout
     { paragraphRect :: Rect Int32
+    -- ^ The containing block (CSS3).
     , spanLayouts :: [SpanLayout]
     }
     deriving (Eq, Read, Show)
 
--- | The resulting layout of each span, which may include multiple bounding
--- boxes if broken over multiple lines.
-data SpanLayout = SpanLayout [Box]
+-- | The resulting layout of each span, which may include multiple fragments if
+-- broken over multiple lines.
+data SpanLayout = SpanLayout [Fragment]
     deriving (Eq, Read, Show)
 
-type Box =
+-- | Box fragment or fragment (CSS3), except that continuous text even within
+-- one line can be split into multiple fragments because of spans or changes in
+-- script.
+type Fragment =
     ( Rect Int32
-    -- ^ Rectangle containing all glyph advances in this box. This is the space
-    -- that the glyphs "take up" and is probably what you want to use for
-    -- detecting position-based events such as mouse clicks.
+    -- ^ Physical position of the fragment within the paragraph, calculated
+    -- using all glyph advances in this fragment and the calculated line height.
+    --
+    -- This is the space that the glyphs "take up" and is probably what you
+    -- want to use for detecting position-based events such as mouse clicks.
     --
     -- Beware that actual glyphs will not be drawn exactly to the borders of
     -- this rectangle -- they may be offset inwards and they can also extend
@@ -112,11 +118,11 @@ type Box =
     , [(GlyphInfo, GlyphPos)]
     )
 
-boxRect :: Box -> Rect Int32
-boxRect = fst
+fragmentRect :: Fragment -> Rect Int32
+fragmentRect = fst
 
 spanRects :: SpanLayout -> [Rect Int32]
-spanRects (SpanLayout boxes) = map boxRect boxes
+spanRects (SpanLayout frags) = map fragmentRect frags
 
 base :: (Num a) => Rect a
 base = Rect 0 0 0 0
@@ -151,7 +157,7 @@ layoutPlain paragraph = ParagraphLayout pRect arrangedLayouts
 layoutSpan :: RS.ResolvedSpan -> SpanLayout
 layoutSpan rs = SpanLayout (map layoutRun $ spanToRuns rs)
 
-layoutRun :: Run -> Box
+layoutRun :: Run -> Fragment
 layoutRun run = (rect, glyphs)
     where
         rs = runOriginalSpan run
@@ -194,26 +200,26 @@ cut arr off s = (end, t)
         end = off + len
         t = Text arr (fromIntegral off) (fromIntegral len)
 
--- | Arrange all boxes in multiple spans in one horizontal direction
+-- | Arrange all fragments in multiple spans in one horizontal direction
 -- and return the final x_offset for continuation.
 arrangeSpansH :: Int32 -> [SpanLayout] -> (Int32, [SpanLayout])
 arrangeSpansH currentX sls = mapAccumL arrangeSpanH currentX sls
 
--- | Arrange all boxes in one span in one horizontal direction
+-- | Arrange all fragments in one span in one horizontal direction
 -- and return the final x_offset for continuation.
 arrangeSpanH :: Int32 -> SpanLayout -> (Int32, SpanLayout)
-arrangeSpanH currentX (SpanLayout boxes) = (nextX, SpanLayout newBoxes)
-    where (nextX, newBoxes) = arrangeBoxesH currentX boxes
+arrangeSpanH currentX (SpanLayout frags) = (nextX, SpanLayout newFragments)
+    where (nextX, newFragments) = arrangeFragmentsH currentX frags
 
--- | Arrange boxes in one horizontal direction
+-- | Arrange fragments in one horizontal direction
 -- and return the final x_offset for continuation.
-arrangeBoxesH :: Int32 -> [Box] -> (Int32, [Box])
-arrangeBoxesH currentX boxes = mapAccumL arrangeBoxH currentX boxes
+arrangeFragmentsH :: Int32 -> [Fragment] -> (Int32, [Fragment])
+arrangeFragmentsH currentX frags = mapAccumL arrangeFragmentH currentX frags
 
 -- | Set the horizontal offset of the given box
 -- and return the x coordinate of its other side for continuation.
-arrangeBoxH :: Int32 -> Box -> (Int32, Box)
-arrangeBoxH currentX (rect, glyphs) = (nextX, (newRect, glyphs))
+arrangeFragmentH :: Int32 -> Fragment -> (Int32, Fragment)
+arrangeFragmentH currentX (rect, glyphs) = (nextX, (newRect, glyphs))
     where
         nextX = currentX + x_size rect
         newRect = rect { x_origin = currentX }
-- 
2.30.2