add a html slot on the right side of a stat plugin (#7384)

## 📝 Summary

<!--
Provide a concise summary of what this pull request is addressing.

If this PR fixes any issues, list them here by number (e.g., Fixes
#123).
-->
New API:
```python
    mo.stat(
        "$20",
        label="Marketing spend",
        slot=mo.md("Hello!"),
    ),
```
<img width="745" height="377" alt="image"
src="https://github.com/user-attachments/assets/9266a5df-bc9c-478d-b664-a7fcdc48bfbb"
/>

## 🔍 Description of Changes

<!--
Detail the specific changes made in this pull request. Explain the
problem addressed and how it was resolved. If applicable, provide before
and after comparisons, screenshots, or any relevant details to help
reviewers understand the changes easily.
-->

## 📋 Checklist

- [x] I have read the [contributor
guidelines](https://github.com/marimo-team/marimo/blob/main/CONTRIBUTING.md).
- [ ] For large changes, or changes that affect the public API: this
change was discussed or approved through an issue, on
[Discord](https://marimo.io/discord?ref=pr), or the community
[discussions](https://github.com/marimo-team/marimo/discussions) (Please
provide a link if applicable).
- [x] I have added tests for the changes made.
- [x] I have run the code and verified that it works as expected.

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: Light2Dark

docs/api/layouts/stat.md

@@ -4,32 +4,69 @@
 
 ```python
 @app.cell
-def __():
+def _():
     active_users = mo.stat(
-        value="1.2M", 
-        label="Active Users", 
-        caption="12k from last month", 
+        value="1.2M",
+        label="Active Users",
+        caption="12k from last month",
         direction="increase"
     )
 
     revenue = mo.stat(
-        value="$4.5M", 
-        label="Revenue", 
-        caption="8k from last quarter", 
+        value="$4.5M",
+        label="Revenue",
+        caption="8k from last quarter",
         direction="increase"
     )
-    
+
     conversion = mo.stat(
-        value="3.8", 
-        label="Conversion Rate", 
-        caption="0.5 from last week", 
+        value="3.8",
+        label="Conversion Rate",
+        caption="0.5 from last week",
         direction="decrease",
     )
-    
+
     mo.hstack([active_users, revenue, conversion], justify="center", gap="2rem")
     return
 ```
 
+```python
+def _():
+    import altair as alt
+    import polars as pl
+
+    alt.renderers.set_embed_options(actions=False)
+
+    df = pl.DataFrame(
+        {
+            "revenue": [30, 20, 70, 45],
+            "dates": ["01/01/2024", "01/03/2024", "01/06/2024", "01/09/2024"],
+        }
+    )
+
+    chart = (
+        alt.Chart(df)
+        .mark_line(interpolate="monotone")
+        .encode(
+            x=alt.X("dates", axis=None),
+            y=alt.Y("revenue", axis=None),
+            tooltip=["dates", "revenue"],
+        )
+        .properties(height=40, width=60, background="transparent")
+        .configure_view(strokeWidth=0)
+    )
+
+    mo.stat(
+        value=df["revenue"][-1],
+        label="Revenue",
+        caption="QoQ Growth",
+        direction="increase",
+        bordered=True,
+        slot=chart,
+    )
+    return
+```
+
 ///
 
 ::: marimo.stat

frontend/src/plugins/impl/vega/vega.css

@@ -8,6 +8,11 @@
   @media (min-width: 500px) {
     min-width: 300px;
   }
+
+  /* For vega embeds in slots, reset the styles to let the user set the width */
+  @container style(--slot: true) {
+    min-width: unset;
+  }
 }
 
 .vega-embed > .chart-wrapper {

frontend/src/plugins/layout/StatPlugin.tsx

@@ -4,8 +4,11 @@ import { TriangleIcon } from "lucide-react";
 import type { JSX } from "react";
 import { useLocale } from "react-aria";
 import { z } from "zod";
+import { getMimeValues } from "@/components/data-table/mime-cell";
 import { cn } from "@/utils/cn";
+import { Logger } from "@/utils/Logger";
 import { prettyNumber } from "@/utils/numbers";
+import { renderHTML } from "../core/RenderHTML";
 import type {
   IStatelessPlugin,
   IStatelessPluginProps,
@@ -18,6 +21,7 @@ interface Data {
   bordered?: boolean;
   direction?: "increase" | "decrease";
   target_direction?: "increase" | "decrease";
+  slot?: object;
 }
 
 export class StatPlugin implements IStatelessPlugin<Data> {
@@ -30,6 +34,7 @@ export class StatPlugin implements IStatelessPlugin<Data> {
     bordered: z.boolean().default(false),
     direction: z.enum(["increase", "decrease"]).optional(),
     target_direction: z.enum(["increase", "decrease"]).default("increase"),
+    slot: z.any().optional(),
   });
 
   render({ data }: IStatelessPluginProps<Data>): JSX.Element {
@@ -44,6 +49,7 @@ export const StatComponent: React.FC<Data> = ({
   bordered,
   direction,
   target_direction,
+  slot,
 }) => {
   const { locale } = useLocale();
 
@@ -71,39 +77,53 @@ export const StatComponent: React.FC<Data> = ({
   const fillColor = onTarget ? "var(--grass-8)" : "var(--red-8)";
   const strokeColor = onTarget ? "var(--grass-9)" : "var(--red-9)";
 
+  const renderSlot = () => {
+    const mimeValues = getMimeValues(slot);
+    if (mimeValues?.[0]) {
+      const { mimetype, data } = mimeValues[0];
+      if (mimetype !== "text/html") {
+        Logger.warn(`Expected text/html, got ${mimetype}`);
+      }
+      return renderHTML({ html: data, alwaysSanitizeHtml: true });
+    }
+  };
+
   return (
     <div
       className={cn(
-        "text-card-foreground",
+        "text-card-foreground p-6",
         bordered && "rounded-xl border shadow bg-card",
       )}
     >
       {label && (
-        <div className="p-6 flex flex-row items-center justify-between space-y-0 pb-2">
+        <div className="flex flex-row items-center justify-between space-y-0 pb-2">
           <h3 className="tracking-tight text-sm font-medium">{label}</h3>
         </div>
       )}
-      <div className="p-6 pt-0">
-        <div className="text-2xl font-bold">{renderPrettyValue()}</div>
-        {caption && (
-          <p className="pt-1 text-xs text-muted-foreground flex align-center">
-            {direction === "increase" && (
-              <TriangleIcon
-                className="w-4 h-4 mr-1 p-0.5"
-                fill={fillColor}
-                stroke={strokeColor}
-              />
-            )}
-            {direction === "decrease" && (
-              <TriangleIcon
-                className="w-4 h-4 mr-1 p-0.5 transform rotate-180"
-                fill={fillColor}
-                stroke={strokeColor}
-              />
-            )}
-            {caption}
-          </p>
-        )}
+      <div className="pt-0 flex flex-row gap-3.5">
+        <div>
+          <div className="text-2xl font-bold">{renderPrettyValue()}</div>
+          {caption && (
+            <p className="pt-1 text-xs text-muted-foreground flex align-center whitespace-nowrap">
+              {direction === "increase" && (
+                <TriangleIcon
+                  className="w-4 h-4 mr-1 p-0.5"
+                  fill={fillColor}
+                  stroke={strokeColor}
+                />
+              )}
+              {direction === "decrease" && (
+                <TriangleIcon
+                  className="w-4 h-4 mr-1 p-0.5 transform rotate-180"
+                  fill={fillColor}
+                  stroke={strokeColor}
+                />
+              )}
+              {caption}
+            </p>
+          )}
+        </div>
+        {slot && <div className="[--slot:true]">{renderSlot()}</div>}
       </div>
     </div>
   );

marimo/_plugins/stateless/stat.py

@@ -1,13 +1,17 @@
 # Copyright 2024 Marimo. All rights reserved.
 from __future__ import annotations
 
-from typing import Literal, Optional, Union
+from typing import Any, Literal, Optional, Union
 
+from marimo._loggers import marimo_logger
+from marimo._output.formatting import as_html
 from marimo._output.hypertext import Html
 from marimo._output.rich_help import mddoc
 from marimo._plugins.core.web_component import build_stateless_plugin
 from marimo._plugins.utils import remove_none_values
 
+Logger = marimo_logger()
+
 
 @mddoc
 def stat(
@@ -17,6 +21,7 @@ def stat(
     direction: Optional[Literal["increase", "decrease"]] = None,
     bordered: bool = False,
     target_direction: Optional[Literal["increase", "decrease"]] = "increase",
+    slot: Optional[Html] = None,
 ) -> Html:
     """Display a statistic.
 
@@ -34,6 +39,7 @@ def stat(
             `increase` when higher values are better, or `decrease`
             when lower values are better. By default the target
             direction is `increase`.
+        slot: an optional Html object to place beside the widget
 
 
     Returns:
@@ -50,7 +56,21 @@ def stat(
                     "direction": direction,
                     "bordered": bordered,
                     "target_direction": target_direction,
+                    "slot": try_convert_to_html(slot),
                 }
             ),
         )
     )
+
+
+def try_convert_to_html(slot: Any) -> Optional[Html]:
+    if slot is None:
+        return None
+
+    try:
+        return as_html(slot)
+    except Exception as e:
+        Logger.error(
+            f"Error converting slot to Html: {e}. Please ensure it is a valid Html object."
+        )
+        return None

marimo/_smoke_tests/stats.py

@@ -2,14 +2,16 @@
 
 import marimo
 
-__generated_with = "0.15.5"
+__generated_with = "0.18.2"
 app = marimo.App()
 
 
 @app.cell
 def _():
     import marimo as mo
-    return (mo,)
+    import polars as pl
+    import altair as alt
+    return alt, mo, pl
 
 
 @app.cell
@@ -74,5 +76,101 @@ def _(mo):
     return
 
 
+@app.cell(hide_code=True)
+def _(alt, mo, pl):
+    findata = pl.DataFrame(
+        {
+            "revenue": [30, 20, 70, 45, 68, 34, 87, 100],
+            "dates": [
+                "01/01/2024",
+                "01/03/2024",
+                "01/06/2024",
+                "01/09/2024",
+                "01/12/2024",
+                "01/15/2024",
+                "01/18/2024",
+                "01/21/2024",
+            ],
+        }
+    )
+
+    alt.renderers.set_embed_options(actions=False)
+
+
+    def create_chart(mark: str) -> alt.Chart:
+        chart = alt.Chart(findata)
+        if mark == "line":
+            chart = chart.mark_line(interpolate="monotone")
+        else:
+            chart = chart.mark_bar()
+        chart = (
+            chart.encode(
+                x=alt.X("dates", axis=None),
+                y=alt.Y("revenue", axis=None),
+                tooltip=["dates", "revenue"],
+            )
+            .properties(height=40, width=60, background="transparent")
+            .configure_view(strokeWidth=0)
+        )
+        return chart
+
+
+    hello_world = mo.Html("<h2><i>Hello, World</i></h2>")
+
+    _stats = [
+        mo.stat(
+            "$100",
+            label="Revenue",
+            caption="+ 10%",
+            direction="increase",
+            bordered=True,
+            slot=create_chart("line"),
+        ),
+        mo.stat(
+            "$20",
+            label="Marketing spend",
+            caption="+ 10%",
+            direction="increase",
+            target_direction="decrease",
+            slot=create_chart("bar"),
+        ),
+        mo.stat(
+            "$80",
+            label="Profit",
+            caption="- 10%",
+            direction="decrease",
+            bordered=True,
+            slot="🚀🧑‍🚀💰",
+        ),
+    ]
+
+    _rich = [
+        mo.stat(
+            "$20",
+            label="Marketing spend",
+            caption="+ 10%",
+            direction="increase",
+            target_direction="decrease",
+            slot=hello_world,
+        ),
+        mo.stat(
+            "2%",
+            label="Churn",
+            caption="- 2%",
+            direction="decrease",
+            bordered=True,
+            target_direction="decrease",
+            slot=_stats[0],
+        ),
+    ]
+
+
+    _first = mo.hstack(_stats, widths="equal", gap=1)
+    _second = mo.hstack(_rich, widths="equal", gap=1)
+
+    mo.vstack([_first, _second])
+    return
+
+
 if __name__ == "__main__":
     app.run()