✨ NEW: grid-item child-direction and child-align options (#15)

Control the direction and alignment of child items within the grid item.

Author: chrisjsewell

README.md

@@ -72,8 +72,6 @@ horizontal card (grid row inside card, picture on left)
 
 subtitle for card (see <https://material.io/components/cards#anatomy>)
 
-paragraph and tab-set in grid-item
-
 rtd PRs not working
 
 octicon in button text shown as raw HTML

docs/css_classes.md

@@ -25,6 +25,8 @@ Some CSS styled text
 
 If you find yourself using a class(es) often, consider opening an issue to request a new role/directive or option!
 
+The `div` directive also has the `style` option, which allows you to add inline CSS styles, although it is not recommended to use this option for most cases.
+
 ## Text
 
 Classes are available for styling and alignment:
@@ -70,16 +72,24 @@ Define the layout of an element and its children (see [`display`](https://develo
 - `sd-d-inline-block`
 - `sd-d-block`
 - `sd-d-grid`
-- `sd-d-flex`
+- `sd-d-flex-row` (align items horizontally)
+- `sd-d-flex-column` (align items vertically)
 - `sd-d-inline-flex`
 
 Variants are also available for screen-sizes (xs, sm, md, lg), e.g. `sd-d-sm-none`.
 
-Items within a flex box can also be aligned:
+Items within a flex box can also be aligned along the major axis or minor axis, dependant on the flex-direction.
+For example, using `sd-d-flex-column` and `sd-align-major-center` will center the items in the vertical direction.
+
+- `sd-align-major-start`
+- `sd-align-major-end`
+- `sd-align-major-center`
+- `sd-align-major-spaced` (spaced to fill the full axis)
+- `sd-align-major-justify` (spaced to fill the full axis, with the first/last item on the edges of the axis)
 
-- `sd-align-items-start`
-- `sd-align-items-end`
-- `sd-align-items-center`
+- `sd-align-minor-start`
+- `sd-align-minor-end`
+- `sd-align-minor-center`
 
 ## Sizing
 

docs/grids.md

@@ -284,9 +284,6 @@ padding
 : Inner padding of grid.
   One (all) or four (top bottom left right) values from: 0, 1, 2, 3, 4, 5.
 
-text-align
-: Default horizontal text alignment: left, right, center or justify
-
 outline
 : Create a border around the grid.
 
@@ -313,12 +310,15 @@ padding
 : Inner padding of grid item.
   One (all) or four (top bottom left right) values from: 0, 1, 2, 3, 4, 5.
 
+child-direction
+: Direction of children in the grid item: `column` (default) or `row`.
+
+child-align
+: Alignment of children, along the `child-direction`: `start` (default), `end`, `center`, `justify` or `spaced`.
+
 outline
 : Create a border around the grid item.
 
-text-align
-: Default horizontal text alignment: left, right, center or justify
-
 class
 : Additional CSS classes for the grid item element.
 

docs/index.md

@@ -7,7 +7,7 @@ sd_hide_title: true
 ::::{grid}
 :reverse:
 :gutter: 2 1 1 1
-:margin: 4 1 1 1
+:margin: 4 4 1 1
 
 :::{grid-item}
 :columns: 12 4 4 4
@@ -20,20 +20,21 @@ sd_hide_title: true
 
 :::{grid-item}
 :columns: 12 8 8 8
-:class: sd-align-items-center sd-fs-3
+:child-align: justify
+:class: sd-fs-3
 
 A sphinx extension for designing beautiful, screen-size responsive web-components.
-:::
-::::
 
 ```{button-ref} get_started
 :color: primary
-:align: center
 :class: sd-fs-5
 
 Get Started
 ```
 
+:::
+::::
+
 Conflict free CSS
 : All CSS classes are prefixed, to avoid conflicts with other frameworks.
 

docs/tabs.md

@@ -36,6 +36,7 @@ See the [Material Design](https://material.io/components/tabs) description for f
 ## Synchronised Tabs
 
 Use the `sync` option to synchronise the selected tab items across multiple tab-sets.
+Note, synchronisation requires that JavaScript is enabled.
 
 ::::{tab-set}
 
@@ -121,10 +122,14 @@ Paragraph
 ::::{tab-set}
 
 :::{tab-item} Label1
+:sync: label-1
+
 Content 1
 :::
 
 :::{tab-item} Label2
+:sync: label-2
+
 Content 2
 :::
 
@@ -134,14 +139,21 @@ Content 2
 ::::::{grid} 1 1 2 2
 
 :::::{grid-item}
+:outline:
+
+Initial paragraph
 
 ::::{tab-set}
 
 :::{tab-item} Label1
+:sync: label-1
+
 Content 1
 :::
 
 :::{tab-item} Label2
+:sync: label-2
+
 Content 2
 :::
 
@@ -150,19 +162,26 @@ Content 2
 :::::
 
 :::::{grid-item}
+:outline:
 
 ::::{tab-set}
 
 :::{tab-item} Label1
+:sync: label-1
+
 Content 1
 :::
 
 :::{tab-item} Label2
+:sync: label-2
+
 Content 2
 :::
 
 ::::
 
+Ending paragraph
+
 :::::
 
 ::::::

sphinx_design/article_info.py

@@ -77,7 +77,7 @@ def run(self) -> List[nodes.Node]:
             # TODO only in html (hide in latex)
             avatar_column = create_component(
                 "grid-item",
-                ["sd-col", "sd-col-auto", "sd-d-flex", "sd-align-items-center"],
+                ["sd-col", "sd-col-auto", "sd-d-flex-row", "sd-align-minor-center"],
             )
             self.set_source_info(avatar_column)
             avatar_classes = ["sd-avatar-sm"]
@@ -103,7 +103,7 @@ def run(self) -> List[nodes.Node]:
 
         info_column = create_component(
             "grid-item",
-            ["sd-col", "sd-d-flex", "sd-align-items-center"],
+            ["sd-col", "sd-d-flex-row", "sd-align-minor-center"],
         )
         self.set_source_info(info_column)
         top_row += info_column
@@ -138,7 +138,7 @@ def run(self) -> List[nodes.Node]:
         if author_text:
             author_column = create_component(
                 "grid-item",
-                ["sd-col", "sd-col-auto", "sd-d-flex", "sd-align-items-center"],
+                ["sd-col", "sd-col-auto", "sd-d-flex-row", "sd-align-minor-center"],
             )
             self.set_source_info(author_column)
             author_nodes = self._parse_text(author_text, parse=parse_fields)
@@ -149,7 +149,7 @@ def run(self) -> List[nodes.Node]:
         if date_text:
             date_column = create_component(
                 "grid-item",
-                ["sd-col", "sd-col-auto", "sd-d-flex", "sd-align-items-center"],
+                ["sd-col", "sd-col-auto", "sd-d-flex-row", "sd-align-minor-center"],
             )
             self.set_source_info(date_column)
             date_icon = nodes.raw(
@@ -166,7 +166,7 @@ def run(self) -> List[nodes.Node]:
         if read_time_text:
             read_time_column = create_component(
                 "grid-item",
-                ["sd-col", "sd-col-auto", "sd-d-flex", "sd-align-items-center"],
+                ["sd-col", "sd-col-auto", "sd-d-flex-row", "sd-align-minor-center"],
             )
             self.set_source_info(read_time_column)
             read_time_icon = nodes.raw(

sphinx_design/compiled/style.min.css

@@ -172,7 +172,7 @@ def run(self):
             newnode = dropdown_main(
                 opened=node["opened"],
                 classes=["sd-sphinx-override", "sd-dropdown"]
-                + (["sd-card"] if use_card else ["sd-d-flex"])
+                + (["sd-card"] if use_card else ["sd-d-flex-column"])
                 + node["container_classes"],
             )
 

sphinx_design/dropdown.py

@@ -93,10 +93,13 @@ def update_css_links(app: Sphinx, env: BuildEnvironment):
 
 def visit_container(self, node: nodes.Node):
     classes = "docutils container"
+    attrs = {}
     if node.get("is_div", False):
         # we don't want the CSS for container for these nodes
         classes = "docutils"
-    self.body.append(self.starttag(node, "div", CLASS=classes))
+    if "style" in node:
+        attrs["style"] = node["style"]
+    self.body.append(self.starttag(node, "div", CLASS=classes, **attrs))
 
 
 def depart_container(self, node: nodes.Node):
@@ -114,11 +117,10 @@ class Div(SphinxDirective):
 
     optional_arguments = 1  # css classes
     final_argument_whitespace = True
-    option_spec = {"name": directives.unchanged}
+    option_spec = {"style": directives.unchanged, "name": directives.unchanged}
     has_content = True
 
     def run(self):
-        self.assert_has_content()
         try:
             if self.arguments:
                 classes = directives.class_option(self.arguments[0])
@@ -130,9 +132,12 @@ def run(self):
                 % (self.name, self.arguments[0])
             )
         node = create_component("div", rawtext="\n".join(self.content), classes=classes)
+        if "style" in self.options:
+            node["style"] = self.options["style"]
         self.set_source_info(node)
         self.add_name(node)
-        self.state.nested_parse(self.content, self.content_offset, node)
+        if self.content:
+            self.state.nested_parse(self.content, self.content_offset, node)
         return [node]
 
 

sphinx_design/extension.py

@@ -105,7 +105,6 @@ class GridDirective(SphinxDirective):
         "gutter": gutter_option,
         "margin": margin_option,
         "padding": padding_option,
-        "text-align": text_align,
         "outline": directives.flag,
         "reverse": directives.flag,
         "class-container": directives.class_option,
@@ -129,7 +128,6 @@ def run(self) -> List[nodes.Node]:
             grid_classes
             + self.options.get("margin", ["sd-mb-4"])
             + self.options.get("padding", [])
-            + self.options.get("text-align", [])
             + (["sd-border-1"] if "outline" in self.options else [])
             + self.options.get("class-container", []),
         )
@@ -170,8 +168,9 @@ class GridItemDirective(SphinxDirective):
         "columns": item_columns_option,
         "margin": margin_option,
         "padding": padding_option,
+        "child-direction": make_choice(["column", "row"]),
+        "child-align": make_choice(["start", "end", "center", "justify", "spaced"]),
         "outline": directives.flag,
-        "text-align": text_align,
         "class": directives.class_option,
     }
 
@@ -188,12 +187,16 @@ def run(self) -> List[nodes.Node]:
             "grid-item",
             [
                 "sd-col",
-                "sd-d-flex",  # TODO is this necessary or should be configurable?
+                f"sd-d-flex-{self.options.get('child-direction', 'column')}",
             ]
             + self.options.get("columns", [])
             + self.options.get("margin", [])
             + self.options.get("padding", [])
-            + self.options.get("text-align", [])
+            + (
+                [f'sd-align-major-{self.options["child-align"]}']
+                if "child-align" in self.options
+                else []
+            )
             + (["sd-border-1"] if "outline" in self.options else [])
             + self.options.get("class", []),
         )
@@ -240,7 +243,7 @@ def run(self) -> List[nodes.Node]:
             "grid-item",
             [
                 "sd-col",
-                "sd-d-flex",  # TODO is this necessary or should be configurable?
+                "sd-d-flex-row",
             ]
             + self.options.get("columns", [])
             + self.options.get("margin", [])