Merge pull request #69 from posit-dev/feat-img-header

feat: `img_header()`

Author: juleswg23

docs/_quarto.yml

@@ -71,6 +71,7 @@ quartodoc:
       contents:
         - fa_icon_repeat
         - gt_fa_rating
+        - img_header
 
     - title: HTML and Formatting
       desc: "" # TODO: add desc

gt_extras/__init__.py

@@ -27,6 +27,8 @@
 
 from .formatting import fmt_pct_extra
 
+from .images import img_header
+
 
 __all__ = [
     "gt_theme_538",
@@ -51,4 +53,5 @@
     "gt_hyperlink",
     "with_tooltip",
     "fmt_pct_extra",
+    "img_header",
 ]

gt_extras/images.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+from great_tables import html
+from great_tables._text import Html
+
+__all__ = ["img_header"]
+
+
+def img_header(
+    label: str,
+    img_url: str,
+    height: float = 60,
+    font_size: int = 12,
+    border_color: str = "black",
+    text_color: str = "black",
+) -> Html:
+    """
+    Create an HTML header with an image and a label, apt for a column label.
+
+    Parameters
+    ----------
+    label
+        The text label to display below the image.
+
+    img_url
+        The URL of the image to display. This can be a filepath or an image on the web.
+
+    height
+        The height of the image in pixels.
+
+    font_size
+        The font size of the label text.
+
+    border_color
+        The color of the border below the image.
+
+    text_color
+        The color of the label text.
+
+    Returns
+    -------
+    html
+        A Great Tables `html` element for the header.
+
+    Examples
+    -------
+    ```{python}
+    import pandas as pd
+    from great_tables import GT, md
+    import gt_extras as gte
+
+    df = pd.DataFrame(
+        {
+            "Category": ["Points", "Rebounds", "Assists", "Blocks", "Steals"],
+            "Hart": [1051, 737, 453, 27, 119],
+            "Brunson": [1690, 187, 475, 8, 60],
+            "Bridges": [1444, 259, 306, 43, 75],
+        }
+    )
+
+    hart_header = gte.img_header(
+        label="Josh Hart",
+        img_url="https://a.espncdn.com/combiner/i?img=/i/headshots/nba/players/full/3062679.png",
+    )
+
+    brunson_header = gte.img_header(
+        label="Jalen Brunson",
+        img_url="https://a.espncdn.com/combiner/i?img=/i/headshots/nba/players/full/3934672.png",
+    )
+
+    bridges_header = gte.img_header(
+        label="Mikal Bridges",
+        img_url="https://a.espncdn.com/combiner/i?img=/i/headshots/nba/players/full/3147657.png",
+    )
+
+    (
+        GT(df, rowname_col="Category")
+        .tab_source_note(md("Images and data courtesy of [ESPN](https://www.espn.com)"))
+        .cols_label(
+            {
+                "Hart": hart_header,
+                "Brunson": brunson_header,
+                "Bridges": bridges_header,
+            }
+        )
+    )
+    ```
+    """
+
+    img_html = f"""
+    <img src="{img_url}" style="
+        height:{height}px;
+        border-bottom:2px solid {border_color};"
+    />
+    """.strip()
+
+    label_html = f"""
+    <div style="
+        font-size:{font_size}px;
+        color:{text_color};
+        text-align:center;
+        width:100%;
+    ">
+        {label}
+    </div>
+    """.strip()
+
+    full_element = f"""
+    <div style="text-align:center;">
+        {img_html}
+        {label_html}
+    </div>
+    """.strip()
+
+    return html(full_element)

gt_extras/plotting.py

@@ -336,7 +336,7 @@ def _make_dot_and_bar_html(
 
         bar_container_style = "position:relative; top:1.2em;"
 
-        html = f'''
+        html = f"""
         <div>
             <div style="{label_div_style}">
                 {dot_category_label}
@@ -347,9 +347,9 @@ def _make_dot_and_bar_html(
                 <div>{_make_bottom_bar_html(bar_val, fill=fill)}</div>
             </div>
         </div>
-        '''
+        """.strip()
 
-        return html.strip()
+        return html
 
     # Validate and get data column
     data_col_name, data_col_vals = _validate_and_get_single_column(
@@ -1400,7 +1400,7 @@ def _make_bar_stack_html(
                 font-size:{font_size}px;
                 color:{_ideal_fgnd_color(_html_color([color])[0])};
             ">{label}</div>
-            """
+            """.strip()
 
             bar_html = f"""
             <div style="
@@ -1411,7 +1411,7 @@ def _make_bar_stack_html(
                 height:{height}px;
                 background:{color};
             ">{label_html}</div>
-            """
+            """.strip()
             if value != 0 and not is_na(gt._tbl_data, value):
                 bars_html.append(bar_html.strip())
                 current_left += bar_width + spacing
@@ -1420,8 +1420,9 @@ def _make_bar_stack_html(
         <div style="position:relative; width:{width}px; height:{height}px;">
             {"".join(bars_html)}
         </div>
-        """
-        return html.strip()
+        """.strip()
+
+        return html
 
     # Throw if `scale_type` is not one of the allowed values
     if scale_type not in ["relative", "absolute"]:

gt_extras/tests/__snapshots__/test_images.ambr

@@ -0,0 +1,4 @@
+# serializer version: 1
+# name: test_img_header_snapshot
+  Html(text='<div style="text-align:center;">\n        <img src="https://example.com/image.png" style="\n        height:60px;\n        border-bottom:2px solid black;"\n    />\n        <div style="\n        font-size:12px;\n        color:black;\n        text-align:center;\n        width:100%;\n    ">\n        Test Label\n    </div>\n    </div>')
+# ---

gt_extras/tests/__snapshots__/test_plotting.ambr

@@ -51,32 +51,28 @@
                   width:32.666666666666664px;
                   height:30px;
                   background:red;
-              ">
-              <div style="
+              "><div style="
                   position:absolute;
                   left:50%;
                   top:50%;
                   transform:translateX(-50%) translateY(-50%);
                   font-size:10px;
                   color:#000000;
-              ">10</div>
-              </div><div style="
+              ">10</div></div><div style="
                   position:absolute;
                   left:34.666666666666664px;
                   top:0px;
                   width:65.33333333333333px;
                   height:30px;
                   background:blue;
-              ">
-              <div style="
+              "><div style="
                   position:absolute;
                   left:50%;
                   top:50%;
                   transform:translateX(-50%) translateY(-50%);
                   font-size:10px;
                   color:#FFFFFF;
-              ">20</div>
-              </div>
+              ">20</div></div>
           </div></td>
     </tr>
     <tr>
@@ -89,32 +85,28 @@
                   width:56.0px;
                   height:30px;
                   background:red;
-              ">
-              <div style="
+              "><div style="
                   position:absolute;
                   left:50%;
                   top:50%;
                   transform:translateX(-50%) translateY(-50%);
                   font-size:10px;
                   color:#000000;
-              ">40</div>
-              </div><div style="
+              ">40</div></div><div style="
                   position:absolute;
                   left:58.0px;
                   top:0px;
                   width:42.0px;
                   height:30px;
                   background:blue;
-              ">
-              <div style="
+              "><div style="
                   position:absolute;
                   left:50%;
                   top:50%;
                   transform:translateX(-50%) translateY(-50%);
                   font-size:10px;
                   color:#FFFFFF;
-              ">30</div>
-              </div>
+              ">30</div></div>
           </div></td>
     </tr>
   </tbody>

gt_extras/tests/test_images.py

@@ -0,0 +1,74 @@
+from great_tables._text import Html
+from gt_extras.images import img_header
+
+
+def test_img_header_snapshot(snapshot):
+    result = img_header(label="Test Label", img_url="https://example.com/image.png")
+    assert snapshot == result
+
+
+def test_img_header_basic():
+    result = img_header(label="Test Label", img_url="https://example.com/image.png")
+
+    assert isinstance(result, Html)
+    assert "Test Label" in result.text
+    assert "https://example.com/image.png" in result.text
+    assert "height:60px;" in result.text
+    assert "border-bottom:2px solid black;" in result.text
+    assert "color:black;" in result.text
+
+
+def test_img_header_custom_height_and_colors():
+    result = img_header(
+        label="Custom Label",
+        img_url="https://example.com/custom.png",
+        height=100,
+        border_color="blue",
+        text_color="red",
+    )
+
+    assert isinstance(result, Html)
+    assert "Custom Label" in result.text
+    assert "https://example.com/custom.png" in result.text
+    assert "height:100px;" in result.text
+    assert "border-bottom:2px solid blue;" in result.text
+    assert "color:red;" in result.text
+
+
+def test_img_header_custom_font_size():
+    result = img_header(
+        label="Font Size Test", img_url="https://example.com/font.png", font_size=20
+    )
+
+    assert isinstance(result, Html)
+    assert "Font Size Test" in result.text
+    assert "font-size:20px;" in result.text
+
+
+def test_img_header_empty_label():
+    result = img_header(label="", img_url="https://example.com/empty_label.png")
+
+    assert isinstance(result, Html)
+    assert "https://example.com/empty_label.png" in result.text
+    assert "<div" in result.text
+    assert "font-size:12px;" in result.text
+
+
+def test_img_header_empty_url():
+    result = img_header(label="Invalid URL Test", img_url="")
+
+    assert isinstance(result, Html)
+    assert "Invalid URL Test" in result.text
+    assert 'src=""' in result.text
+
+
+def test_img_header_no_border():
+    result = img_header(
+        label="No Border Test",
+        img_url="https://example.com/no_border.png",
+        border_color="transparent",
+    )
+
+    assert isinstance(result, Html)
+    assert "No Border Test" in result.text
+    assert "border-bottom:2px solid transparent;" in result.text