From 72d019227523f51548e24e8071972a00a11aff5a Mon Sep 17 00:00:00 2001
From: Adrian Cochrane <adrian@openwork.nz>
Date: Tue, 11 Apr 2023 13:49:52 +1200
Subject: [PATCH] Reference-document rest of CSS implementation, disable
 table-related values of CSS display as unsupported.

---
 Graphics/Layout/CSS.hs | 28 +++++++++++++++++++++++++---
 1 file changed, 25 insertions(+), 3 deletions(-)

diff --git a/Graphics/Layout/CSS.hs b/Graphics/Layout/CSS.hs
index 394e53a..8b7920f 100644
--- a/Graphics/Layout/CSS.hs
+++ b/Graphics/Layout/CSS.hs
@@ -16,25 +16,42 @@ import Graphics.Layout.CSS.Font
 import Graphics.Layout.Grid.CSS
 import Graphics.Layout.Inline.CSS
 
+-- | Parsed CSS properties relevant to layout.
 data CSSBox a = CSSBox {
+    -- | Which layout formula to use, a.k.a. parsed CSS display property.
     display :: Display,
+    -- | (Unused) Parsed CSS box-sizing
     boxSizing :: BoxSizing,
-    cssBox :: PaddedBox Unitted Unitted, -- Some units need to be resolved per font. calc()?
+    -- | sizing, margins, border-width, & padding CSS properties.
+    -- Stores units in case they're needed for font-related units.
+    cssBox :: PaddedBox Unitted Unitted, -- calc()?
+    -- | Query parameters describing desired font.
     font :: Pattern,
+    -- | Additional font-related CSS properties.
     font' :: CSSFont,
+    -- | Caller-specified data, to parse additional CSS properties.
     inner :: a,
+    -- | Grid-related CSS properties.
     gridStyles :: CSSGrid,
+    -- | Grid item related CSS properties.
     cellStyles :: CSSCell,
+    -- | inline-related CSS properties.
     inlineStyles :: CSSInline,
+    -- | Parsed CSS caption-side.
     captionBelow :: Bool,
+    -- | Parsed widows & orphans controlling pagination.
     pageOptions :: PageOptions
 }
+-- | Possible values for CSS box-sizing.
 data BoxSizing = BorderBox | ContentBox
+-- | Empty border, to use as default value.
 noborder = Border (0,"px") (0,"px") (0,"px") (0,"px")
 
+-- | Possibly values for CSS display property.
 data Display = Block | Grid | Inline | Table | None |
     TableRow | TableHeaderGroup | TableRowGroup | TableFooterGroup | TableCell |
     TableColumn | TableColumnGroup | TableCaption deriving Eq
+-- | Can the display value contain table-rows?
 rowContainer CSSBox { display = d } =
     d `elem` [Table, TableHeaderGroup, TableRowGroup, TableFooterGroup]
 
@@ -122,7 +139,7 @@ instance PropertyParser a => PropertyParser (CSSBox a) where
     longhand _ self "display" [Ident "block"] = Just self { display = Block }
     longhand _ self "display" [Ident "none"] = Just self { display = None }
     longhand _ self "display" [Ident "grid"] = Just self { display = Grid }
-    longhand _ self "display" [Ident "table"] = Just self { display = Table }
+    {-longhand _ self "display" [Ident "table"] = Just self { display = Table }
     longhand CSSBox { display = Table } self "display" [Ident "table-row-group"] =
         Just self { display=TableRowGroup }
     longhand CSSBox { display = Table } self "display" [Ident "table-header-group"] =
@@ -138,7 +155,7 @@ instance PropertyParser a => PropertyParser (CSSBox a) where
     longhand CSSBox { display = TableColumnGroup } self "display" [Ident "table-column"] =
         Just self { display = TableColumn }
     longhand CSSBox { display = Table } self "display" [Ident "table-caption"] =
-        Just self { display=TableCaption }
+        Just self { display=TableCaption } -}
     longhand _ self "display" [Ident "inline"] = Just self { display = Inline }
     longhand _ self "display" [Ident "initial"] = Just self { display = Inline }
 
@@ -169,8 +186,10 @@ instance PropertyParser a => PropertyParser (CSSBox a) where
     longhand a b c d | Just inner' <- longhand (inner a) (inner b) c d = Just b {
         inner = inner'
       }
+    -- TODO Facilitate length-lowering for inner value?
     longhand _ _ _ _ = Nothing
 
+-- | Desugar parsed CSS into more generic layout parameters.
 finalizeCSS :: PropertyParser x => Font' -> Font' -> StyleTree (CSSBox x) ->
         LayoutItem Length Length x
 finalizeCSS root parent StyleTree { style = self'@CSSBox { display = None } } =
@@ -206,6 +225,7 @@ finalizeCSS root parent self@StyleTree {
 finalizeCSS' sysfont self@StyleTree { style = self' } =
     finalizeCSS (pattern2font (font self') (font' self') sysfont sysfont) sysfont self
 
+-- | Desugar a sequence of child nodes, taking care to capture runs of inlines.
 finalizeChilds :: PropertyParser x => Font' -> Font' -> x -> [StyleTree (CSSBox x)] ->
         [LayoutItem Length Length x]
 finalizeChilds root parent style' (StyleTree { style = CSSBox { display = None } }:childs) =
@@ -242,9 +262,11 @@ finalizeChilds root parent style' childs@(child:childs')
     flattenTree [] = ParagraphBuilder "" []
 finalizeChilds _ _ _ [] = []
 
+-- | Desugar most units, possibly in reference to given font.
 finalizeBox self@CSSBox { cssBox = box } font_ =
     mapY' (flip finalizeLength font_) $ mapX' (flip finalizeLength font_) box
 
+-- | (Unused, incomplete) Desugar a styletree of table elements to a grid layout.
 finalizeTable root parent val childs = LayoutFlow val lengthBox [] -- Placeholder!
 {- finalizeTable root parent val childs = LayoutGrid val grid $ zip cells' childs'
   where -- FIXME? How to handle non-table items in <table>?
-- 
2.30.2