Metadata-Version: 2.4
Name: marimo-utils
Version: 0.8.1
Summary: Utilities for working with marimo notebooks: Pydantic model display plus a Tailwind + shadcn UI primitives package
Project-URL: Homepage, https://github.com/drothermel/marimo_utils
Project-URL: Repository, https://github.com/drothermel/marimo_utils
Author-email: Danielle Rothermel <danielle.rothermel@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: display,marimo,notebooks,plotly,pydantic,shadcn,tailwind,ui
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Requires-Dist: anywidget>=0.9
Requires-Dist: dr-widget==0.2.0
Requires-Dist: marimo[recommended]>=0.19.4
Requires-Dist: pandas>=2.0
Requires-Dist: plotly>=6.7.0
Requires-Dist: pydantic>=2.12.5
Requires-Dist: python-lucide>=0.2.24
Requires-Dist: tailwind-merge>=0.3.3
Description-Content-Type: text/markdown

# marimo-utils

Utilities for working with marimo notebooks.

## Installation

```bash
pip install marimo-utils
```

## Usage

### `marimo_utils.pydantic` — Pydantic model display in marimo

Adds marimo's `_display_` protocol to Pydantic models so the last expression in a cell renders class name, source path, and field values.

```python
from pydantic import BaseModel
from marimo_utils import add_marimo_display

@add_marimo_display()
class MyConfig(BaseModel):
    name: str
    value: int
```

When a `MyConfig` instance is the last expression in a marimo cell, it renders with the class name, source file path, and all field values.

#### Package layout (`marimo_utils`)

| Path | Role |
|---|---|
| `pydantic/` | Pydantic ↔ marimo integration — `add_marimo_display()`, `render_model()` |
| `ui/` | Styled widget + chart toolkit (see below) |

Import from `marimo_utils` or `marimo_utils.pydantic` in notebooks; internal paths may change between releases.

### `marimo_utils.ui` — Tailwind + shadcn primitives for marimo

Pydantic-backed UI primitives that render through Tailwind (Play CDN) themed with shadcn/ui defaults. The package ships card components (`Card`, `CardTitle`, `CardDescription`), small composable atoms (`Badge`, `DataItem`, `Stamp`, `date_stamp`, `project_stamp`, `LabeledList`, `LucideIcon`), and a plotly-backed chart family (`BarChart`, `HeatmapChart`, `HistogramChart`, `LineChart`, `PieChart`, `ScatterChart`, `ViolinChart`) sharing a common `PlotlyChart` base. Call `bootstrap_tailwind()` once in a notebook to inject shadcn's CSS variables on `:root` plus the utility rules that depend on them, then load the Tailwind CDN.

```python
import marimo as mo
from marimo_utils.ui import (
    BarChart,
    BarItem,
    Card,
    CardWidth,
    ChartColor,
    bootstrap_tailwind,
)

bootstrap_tailwind()

Card(
    title="Class Distribution",
    description="Class counts across the training split",
    content=BarChart(
        items=[
            BarItem(label="Class A", value=5),
            BarItem(label="Class B", value=10),
            BarItem(label="Class C", value=5, color=ChartColor.THREE),
            BarItem(label="Class D", value=1),
        ],
        height=220,
    ),
    width=CardWidth.NARROW,
).render()
```

Components use shadcn's stock variant names (`default`, `secondary`, `destructive`, `outline`). Meta rows use registry-backed stamp builders — `date_stamp()` and `project_stamp()` return a `Stamp` with configurable empty text, spacing, and icons. Charts cycle through the `--chart-1` → `--chart-5` palette by default; pin specific items with `color=ChartColor.X`. Every `PlotlyChart` subclass renders through the same contract: plotly HTML with `responsive: true` + `include_plotlyjs="cdn"`, a `.reactive()` opt-in for marimo-reactive widgets, and a `Card`-friendly transparent background. `<script>`-bearing HTML (plotly) is routed through `dr_widget.inline.ActiveHtml` so charts execute inside marimo's React tree.

See [`nbs/ui_components.py`](./nbs/ui_components.py) for a live demo of every atom, chart, and card variant side-by-side.

#### Styling conventions (`styles.py`)

Tailwind class strings are centralized in `marimo_utils.ui.styles` as named enums and constants. Components compose them with `cn()` from `drhtml` (tailwind-merge); pass per-instance overrides through each component's `klass` prop last.

| Group | Symbols | Role |
|---|---|---|
| Layout | `DivLayouts`, `SpanLayouts` | Card sections, inline rows, key/value rows, icon frame |
| Typography | `Typography` | Text size, weight, and color |
| Sizing | `IconSize`, `CardWidth`, `Padding` | Icon dimensions, card widths, badge padding |
| Surface | `BORDER`, `BADGE_FOCUS`, `Background` | Shared border/radius/shadow, focus ring, fills and hovers |
| Badges | `BadgeVariant` | Shadcn badge variants (aliases into `Background`) |

Contributors and agents: avoid raw layout Tailwind in components; add or reuse a named enum or shared constant instead.

#### Package layout (`marimo_utils.ui`)

| Path | Role |
|---|---|
| `setup/` | Notebook bootstrap — `bootstrap_tailwind()` and shadcn CSS injection |
| `core/` | HTML DSL — `drhtml` tag builders, `cn()`, `rendering` helpers |
| `styles.py` | Shared Tailwind token enums and constants |
| `components/` | UI widgets (`Card`, `Badge`, `Stamp`, …) |
| `charts/` | Plotly chart family and `colors` palette helpers |

Import from `marimo_utils.ui` in notebooks; internal paths may change between releases.

## Changelog

See [CHANGELOG.md](./CHANGELOG.md) for release notes and migration guides.
