hotdata-marimo 0.1.0__tar.gz

hotdata_marimo-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,70 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v[0-9]*'
+
+concurrency:
+  group: pypi-publish-${{ github.ref_name }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        with:
+          python-version: '3.12'
+
+      - name: Install build tooling
+        run: python -m pip install --upgrade build twine
+
+      - name: Verify tag matches pyproject version
+        run: |
+          # Release tags must start with `v` followed by a PEP 440 version (e.g. v1.2.3, v1.2.3a1).
+          if [[ ! "$GITHUB_REF_NAME" =~ ^v[0-9] ]]; then
+            echo "Release tag '$GITHUB_REF_NAME' must start with 'v' followed by a digit (e.g. v1.0.0)" >&2
+            exit 1
+          fi
+          tag="${GITHUB_REF_NAME#v}"
+          pkg_version=$(python -c "import tomllib,pathlib; print(tomllib.loads(pathlib.Path('pyproject.toml').read_text())['project']['version'])")
+          if [ "$tag" != "$pkg_version" ]; then
+            echo "Release tag ($tag) does not match pyproject.toml version ($pkg_version)" >&2
+            exit 1
+          fi
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Check distribution metadata
+        run: python -m twine check --strict dist/*
+
+      - uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/hotdata-marimo
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0 # v5
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish via Trusted Publishing
+        uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # v1.13.0

hotdata_marimo-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+.DS_Store
+
+# Python
+__pycache__/
+*.py[cod]
+*.pyd
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Virtualenvs
+.venv/
+venv/
+
+# Build artifacts
+dist/
+build/
+*.egg-info/
+
+# Marimo editor session (local UI state; keep notebook source as examples/*.py only)
+**/__marimo__/session/
+

hotdata_marimo-0.1.0/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-05-06
+
+### Added
+
+- Initial release: `HotdataClient`, `sql_editor`, `table_browser`, `query_result`, and `from_env`.
+- `connection_status` callout and `mo.ui.hotdata_*` aliases (via `register_mo_ui_hotdata_aliases` on import).
+- SQL editor: run button with cached results, spinner while executing, and prompt to re-run after SQL edits.

hotdata_marimo-0.1.0/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: hotdata-marimo
+Version: 0.1.0
+Summary: Marimo integration for Hotdata runtime
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: hotdata-runtime>=0.1.0
+Requires-Dist: marimo>=0.10.0
+Description-Content-Type: text/markdown
+
+# hotdata-marimo
+
+Marimo UI helpers for [Hotdata](https://hotdata.dev): run SQL from a notebook, browse catalog metadata, and render results as tables.
+
+## Features
+
+- **Workspace-aware setup** — build a `HotdataClient` from environment variables, or use `workspace_selector_from_env()` to choose a workspace interactively when no workspace is pinned.
+- **Connection health** — show a compact status callout with API, workspace, and optional sandbox context.
+- **Catalog browsing** — browse Hotdata connections, schemas, tables, and columns from Marimo UI controls.
+- **SQL editor widget** — run SQL against Hotdata, cache the latest successful result, and render results in downstream reactive cells.
+- **Native `mo.sql` engine** — register `HotdataMarimoEngine` so Marimo SQL cells can execute through a live `HotdataClient` with `engine=client`.
+- **Result display helpers** — render query results, recent results, and run history as notebook-friendly UI.
+- **Marimo UI aliases** — importing `hotdata_marimo` attaches helpers such as `mo.ui.hotdata_sql_editor` and `mo.ui.hotdata_table_browser` for discoverability.
+
+## Install
+
+```bash
+uv pip install hotdata-marimo
+# or: pip install hotdata-marimo
+```
+
+Requires Python 3.10+, **Marimo**, and [**hotdata-runtime**](https://github.com/hotdata-dev/hotdata-runtime) (Hotdata SDK + runtime/session semantics — pulled in automatically when you `pip install hotdata-marimo`).
+
+## Environment
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `HOTDATA_API_KEY` | Yes | API key for the Hotdata API |
+| `HOTDATA_API_URL` | No | API base URL (default: `https://api.hotdata.dev`) |
+| `HOTDATA_WORKSPACE` | No | Workspace id; if unset, the first active workspace is used |
+| `HOTDATA_SANDBOX` | No | Sandbox session id, passed through to the SDK |
+
+## Minimal notebook
+
+```python
+import marimo as mo
+import hotdata_marimo as hm
+
+client = hm.from_env()
+editor = hm.sql_editor(client, default_sql="SELECT 1 AS ok")
+return editor.ui
+```
+
+```python
+return hm.query_result(editor.result)
+```
+
+Importing `hotdata_marimo` registers discoverability aliases on Marimo’s UI namespace, so you can also use `mo.ui.hotdata_sql_editor`, `mo.ui.hotdata_table_browser`, `mo.ui.hotdata_query_result`, and `mo.ui.hotdata_connection_status`.
+
+Use `hm.connection_status(client)` (or `mo.ui.hotdata_connection_status(client)`) for a small API/workspace health callout.
+
+## Marimo SQL Cells
+
+Register the Hotdata SQL engine once during setup, then pass a `HotdataClient` to Marimo SQL cells:
+
+```python
+import hotdata_marimo as hm
+
+hm.register_hotdata_sql_engine()
+client = hm.from_env()
+```
+
+```python
+_df = mo.sql(
+    """
+    SELECT 1 AS example_value
+    """,
+    engine=client,
+)
+```
+
+The engine also exposes Hotdata catalog metadata to Marimo's data-source UI. Hotdata connections are labeled **Hotdata** in the SQL connection picker.
+
+## Two-cell pattern
+
+Keep the editor in one cell and consume `editor.result` in another. The editor caches the last successful run so downstream cells do not re-query the API on every refresh; click **Run on Hotdata** again after you change SQL. While a query is running, a Marimo status spinner is shown.
+
+Marimo only shows **what you `return` from a cell**. Calling `mo.vstack(...)` or `hm.query_result(...)` without returning it produces no visible output.
+
+See `examples/demo.py` for a full runnable notebook flow.
+
+## Examples
+
+- `examples/demo.py` — tabbed explorer with workspace selection, connection health, recent results (selectable table), run history, and a native `mo.sql` cell.
+
+Run locally (single-user machine):
+
+```bash
+uv run marimo edit examples/demo.py --no-token
+```
+
+On a **shared or networked host**, omit `--no-token` and use the access token printed in the terminal URL. Without it, anyone who can reach the Marimo port can run queries against your Hotdata workspace.
+
+## Layout
+
+This repo is intentionally thin: **API client, env helpers, and result models** live in **hotdata-runtime**; **hotdata-marimo** only adds Marimo widgets (`sql_editor`, `table_browser`, `display` for tables/status/history, `workspace_selector`). Import `HotdataClient` / `QueryResult` / `from_env` from **`hotdata_marimo`** or directly from **`hotdata_runtime`**.
+
+## Development
+
+This package depends on [**hotdata-runtime**](https://github.com/hotdata-dev/hotdata-runtime) (PyPI name `hotdata-runtime`). Development uses **uv**; keep a sibling checkout at `../hotdata-runtime` so the lockfile resolves the runtime from disk (see `[tool.uv.sources]` in `pyproject.toml`).
+
+```bash
+uv sync --locked
+uv run pytest
+marimo edit examples/demo.py --no-token
+```
+
+To pin **hotdata-runtime** from Git instead of the sibling path, remove the `[tool.uv.sources]` block, set the dependency line as needed, and run `uv lock` again.
+
+For a **publishable** `uv.lock` (CI that only clones this repo), remove `[tool.uv.sources]`, point `hotdata-runtime` at PyPI or `git+https://…`, then `uv lock`.
+
+The **`[project] name`** in [hotdata-runtime](https://github.com/hotdata-dev/hotdata-runtime) `pyproject.toml` is **`hotdata-runtime`** and the import package is **`hotdata_runtime`**.
+
+Use **`--no-token`** for local development so the editor does not redirect to `/auth/login` (session auth is easy to hit with a global Marimo config). For a public or shared machine, omit it and use the printed URL with an access token instead.

hotdata_marimo-0.1.0/README.md

@@ -0,0 +1,114 @@
+# hotdata-marimo
+
+Marimo UI helpers for [Hotdata](https://hotdata.dev): run SQL from a notebook, browse catalog metadata, and render results as tables.
+
+## Features
+
+- **Workspace-aware setup** — build a `HotdataClient` from environment variables, or use `workspace_selector_from_env()` to choose a workspace interactively when no workspace is pinned.
+- **Connection health** — show a compact status callout with API, workspace, and optional sandbox context.
+- **Catalog browsing** — browse Hotdata connections, schemas, tables, and columns from Marimo UI controls.
+- **SQL editor widget** — run SQL against Hotdata, cache the latest successful result, and render results in downstream reactive cells.
+- **Native `mo.sql` engine** — register `HotdataMarimoEngine` so Marimo SQL cells can execute through a live `HotdataClient` with `engine=client`.
+- **Result display helpers** — render query results, recent results, and run history as notebook-friendly UI.
+- **Marimo UI aliases** — importing `hotdata_marimo` attaches helpers such as `mo.ui.hotdata_sql_editor` and `mo.ui.hotdata_table_browser` for discoverability.
+
+## Install
+
+```bash
+uv pip install hotdata-marimo
+# or: pip install hotdata-marimo
+```
+
+Requires Python 3.10+, **Marimo**, and [**hotdata-runtime**](https://github.com/hotdata-dev/hotdata-runtime) (Hotdata SDK + runtime/session semantics — pulled in automatically when you `pip install hotdata-marimo`).
+
+## Environment
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `HOTDATA_API_KEY` | Yes | API key for the Hotdata API |
+| `HOTDATA_API_URL` | No | API base URL (default: `https://api.hotdata.dev`) |
+| `HOTDATA_WORKSPACE` | No | Workspace id; if unset, the first active workspace is used |
+| `HOTDATA_SANDBOX` | No | Sandbox session id, passed through to the SDK |
+
+## Minimal notebook
+
+```python
+import marimo as mo
+import hotdata_marimo as hm
+
+client = hm.from_env()
+editor = hm.sql_editor(client, default_sql="SELECT 1 AS ok")
+return editor.ui
+```
+
+```python
+return hm.query_result(editor.result)
+```
+
+Importing `hotdata_marimo` registers discoverability aliases on Marimo’s UI namespace, so you can also use `mo.ui.hotdata_sql_editor`, `mo.ui.hotdata_table_browser`, `mo.ui.hotdata_query_result`, and `mo.ui.hotdata_connection_status`.
+
+Use `hm.connection_status(client)` (or `mo.ui.hotdata_connection_status(client)`) for a small API/workspace health callout.
+
+## Marimo SQL Cells
+
+Register the Hotdata SQL engine once during setup, then pass a `HotdataClient` to Marimo SQL cells:
+
+```python
+import hotdata_marimo as hm
+
+hm.register_hotdata_sql_engine()
+client = hm.from_env()
+```
+
+```python
+_df = mo.sql(
+    """
+    SELECT 1 AS example_value
+    """,
+    engine=client,
+)
+```
+
+The engine also exposes Hotdata catalog metadata to Marimo's data-source UI. Hotdata connections are labeled **Hotdata** in the SQL connection picker.
+
+## Two-cell pattern
+
+Keep the editor in one cell and consume `editor.result` in another. The editor caches the last successful run so downstream cells do not re-query the API on every refresh; click **Run on Hotdata** again after you change SQL. While a query is running, a Marimo status spinner is shown.
+
+Marimo only shows **what you `return` from a cell**. Calling `mo.vstack(...)` or `hm.query_result(...)` without returning it produces no visible output.
+
+See `examples/demo.py` for a full runnable notebook flow.
+
+## Examples
+
+- `examples/demo.py` — tabbed explorer with workspace selection, connection health, recent results (selectable table), run history, and a native `mo.sql` cell.
+
+Run locally (single-user machine):
+
+```bash
+uv run marimo edit examples/demo.py --no-token
+```
+
+On a **shared or networked host**, omit `--no-token` and use the access token printed in the terminal URL. Without it, anyone who can reach the Marimo port can run queries against your Hotdata workspace.
+
+## Layout
+
+This repo is intentionally thin: **API client, env helpers, and result models** live in **hotdata-runtime**; **hotdata-marimo** only adds Marimo widgets (`sql_editor`, `table_browser`, `display` for tables/status/history, `workspace_selector`). Import `HotdataClient` / `QueryResult` / `from_env` from **`hotdata_marimo`** or directly from **`hotdata_runtime`**.
+
+## Development
+
+This package depends on [**hotdata-runtime**](https://github.com/hotdata-dev/hotdata-runtime) (PyPI name `hotdata-runtime`). Development uses **uv**; keep a sibling checkout at `../hotdata-runtime` so the lockfile resolves the runtime from disk (see `[tool.uv.sources]` in `pyproject.toml`).
+
+```bash
+uv sync --locked
+uv run pytest
+marimo edit examples/demo.py --no-token
+```
+
+To pin **hotdata-runtime** from Git instead of the sibling path, remove the `[tool.uv.sources]` block, set the dependency line as needed, and run `uv lock` again.
+
+For a **publishable** `uv.lock` (CI that only clones this repo), remove `[tool.uv.sources]`, point `hotdata-runtime` at PyPI or `git+https://…`, then `uv lock`.
+
+The **`[project] name`** in [hotdata-runtime](https://github.com/hotdata-dev/hotdata-runtime) `pyproject.toml` is **`hotdata-runtime`** and the import package is **`hotdata_runtime`**.
+
+Use **`--no-token`** for local development so the editor does not redirect to `/auth/login` (session auth is easy to hit with a global Marimo config). For a public or shared machine, omit it and use the printed URL with an access token instead.

hotdata_marimo-0.1.0/TODO.md

@@ -0,0 +1,40 @@
+# hotdata-marimo — next steps
+
+## Near term (build on MVP)
+
+- [x] **Workspace selector** — When `HOTDATA_WORKSPACE` is unset and multiple workspaces exist, expose `mo.ui.dropdown` (or similar) and rebuild the client when the choice changes.
+- [x] **Connection status** — Small status chip (API reachable, workspace id, optional sandbox) using a lightweight health or `workspaces`/`connections` probe.
+- [ ] **Query cancel** — Wire cancel to the query-run API if/when exposed in the OpenAPI client; surface a Cancel control next to Run.
+- [x] **`mo.ui.hotdata_*` aliases** — Re-export or thin wrappers: `hotdata_sql_editor`, `hotdata_table_browser`, `hotdata_query_result`, `hotdata_connection_picker` for discoverability.
+- [x] **Tests** — Unit tests with mocked SDK responses; optional integration tests gated on `HOTDATA_API_KEY` (mirror sdk-python patterns).
+
+## SQL editor & execution
+
+- [ ] **Schema-aware autocomplete** — anywidget (or CodeMirror) + Hotdata `information_schema` / column metadata for table/column suggestions.
+- [x] **Async UX** — Progress text or spinner while polling query runs; optional configurable timeouts.
+- [x] **Run history panel** — `QueryRunsApi.list_query_runs` + metadata (latency, touched tables, `result_id`) in a side panel or collapsible.
+- [x] **Rerun / clear** — Explicit rerun without relying only on `run_button` semantics; optional “clear result” action.
+
+## Results
+
+- [x] **Pagination / LIMIT guidance** — Surface row counts vs limit; warn when result is truncated if the API exposes it.
+- [ ] **Export** — CSV / Parquet download links or buttons (align with Hotdata results/export APIs when available).
+- [x] **Cached result reuse** — Prefer `get_result(result_id)` over re-running identical SQL when `result_id` is known.
+- [ ] **Materialization / cache status** — Show persistence state when the API returns it (`processing` / `ready` / errors).
+
+## Data discovery
+
+- [x] **Connection picker** — Filter catalog by connection; map display names to ids consistently.
+- [x] **Schema search** — Text filter over tables/columns without loading full dropdowns for huge catalogs.
+- [ ] **Table preview** — `LIMIT` preview query from browser selection (optional second query).
+- [ ] **Generated queries** — Starters beyond `SELECT *`: profile/join templates from selected tables.
+
+## App mode
+
+- [ ] **Deployable Marimo app** — Layout recipe (sidebar explorer + editor + result) and docs for `marimo run` / WASM constraints.
+- [ ] **Auth in apps** — Document env injection for deployed apps; avoid embedding API keys in notebooks.
+
+## Docs & packaging
+
+- [x] **README** — Install, env vars, minimal notebook example, and “two-cell” pattern for `editor.result` + `mo.stop`.
+- [x] **Changelog** — Keep `CHANGELOG.md` once versions ship.

hotdata_marimo-0.1.0/examples/demo.py

@@ -0,0 +1,85 @@
+import marimo
+
+__generated_with = "0.23.5"
+app = marimo.App()
+
+
+@app.cell
+def _():
+    import os
+
+    import marimo as mo
+
+    import hotdata_marimo as hm
+
+    hm.register_hotdata_sql_engine()
+    return hm, mo, os
+
+
+@app.cell
+def _(hm, mo, os):
+    mo.stop(
+        not os.environ.get("HOTDATA_API_KEY"),
+        mo.callout(
+            mo.md(
+                "Add **HOTDATA_API_KEY** to your environment "
+                "to run this example."
+            ),
+            kind="warn",
+        ),
+    )
+    workspace = hm.workspace_selector_from_env()
+    return (workspace,)
+
+
+@app.cell
+def _(hm, workspace):
+    client = workspace.client
+    status = hm.connections_panel(client)
+    recent = hm.recent_results(client, limit=20)
+    history = hm.run_history(client, limit=10)
+    return client, history, recent, status
+
+
+@app.cell
+def _(mo):
+    mo.md(r"""
+    ## HotData explorer
+    Use the tabs below to switch between workspaces, connection status, recent results, and run history.
+
+    On a shared or networked host, run Marimo **without** `--no-token` and open the printed URL
+    with its access token so only you can use this notebook.
+    """)
+    return
+
+
+@app.cell
+def _(recent):
+    recent_tab = recent.tab_ui
+    return (recent_tab,)
+
+
+@app.cell
+def _(history, mo, recent_tab, status, workspace):
+    mo.ui.tabs({
+        "Workspaces": workspace.ui,
+        "Connections": status,
+        "Recent results": recent_tab,
+        "Run history": history,
+    })
+    return
+
+
+@app.cell
+def _(client, mo):
+    _df = mo.sql(
+        """
+        SELECT 1 AS example_value
+        """,
+        engine=client
+    )
+    return
+
+
+if __name__ == "__main__":
+    app.run()

hotdata_marimo-0.1.0/hotdata_marimo/__init__.py

@@ -0,0 +1,80 @@
+"""Marimo-native UI and helpers for Hotdata (built on hotdata-runtime)."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("hotdata-marimo")
+except PackageNotFoundError:
+    __version__ = "0.0.0+unknown"
+
+from hotdata_runtime import HotdataClient, QueryResult, from_env
+
+from hotdata_marimo.display import (
+    RecentResults,
+    connection_status,
+    connections_panel,
+    query_result,
+    recent_results,
+    run_history,
+)
+from hotdata_marimo.sql_engine import (
+    HotdataMarimoEngine,
+    register_hotdata_sql_engine,
+    unregister_hotdata_sql_engine,
+)
+from hotdata_marimo.sql_editor import SqlEditor, sql_editor
+from hotdata_marimo.table_browser import TableBrowser, connection_picker, table_browser
+from hotdata_marimo.workspace_selector import WorkspaceSelector, workspace_selector_from_env
+
+__all__ = [
+    "__version__",
+    "HotdataClient",
+    "HotdataMarimoEngine",
+    "QueryResult",
+    "RecentResults",
+    "SqlEditor",
+    "TableBrowser",
+    "WorkspaceSelector",
+    "connection_picker",
+    "connection_status",
+    "connections_panel",
+    "from_env",
+    "hotdata_connection_picker",
+    "hotdata_query_result",
+    "hotdata_recent_results",
+    "hotdata_sql_editor",
+    "hotdata_table_browser",
+    "hotdata_workspace_selector",
+    "query_result",
+    "recent_results",
+    "register_hotdata_sql_engine",
+    "register_mo_ui_hotdata_aliases",
+    "run_history",
+    "sql_editor",
+    "table_browser",
+    "unregister_hotdata_sql_engine",
+    "workspace_selector_from_env",
+]
+
+hotdata_sql_editor = sql_editor
+hotdata_table_browser = table_browser
+hotdata_query_result = query_result
+hotdata_connection_picker = connection_picker
+hotdata_workspace_selector = workspace_selector_from_env
+hotdata_recent_results = recent_results
+
+
+def register_mo_ui_hotdata_aliases() -> None:
+    """Attach Hotdata helpers to ``marimo.ui`` for discoverability (``mo.ui.hotdata_*``)."""
+    import marimo as mo
+
+    mo.ui.hotdata_sql_editor = hotdata_sql_editor  # type: ignore[attr-defined]
+    mo.ui.hotdata_table_browser = hotdata_table_browser  # type: ignore[attr-defined]
+    mo.ui.hotdata_query_result = hotdata_query_result  # type: ignore[attr-defined]
+    mo.ui.hotdata_connection_status = connection_status  # type: ignore[attr-defined]
+    mo.ui.hotdata_connection_picker = hotdata_connection_picker  # type: ignore[attr-defined]
+    mo.ui.hotdata_workspace_selector = hotdata_workspace_selector  # type: ignore[attr-defined]
+    mo.ui.hotdata_recent_results = hotdata_recent_results  # type: ignore[attr-defined]
+
+
+register_mo_ui_hotdata_aliases()

hotdata_marimo-0.1.0/hotdata_marimo/_options.py

@@ -0,0 +1,107 @@
+"""Shared dropdown option helpers for Marimo UI widgets."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+import marimo as mo
+
+from hotdata_runtime import HotdataClient
+
+
+def unique_label_options(
+    pairs: list[tuple[str, str]],
+    *,
+    disambiguate: Callable[[str, str, int], str] | None = None,
+) -> dict[str, str]:
+    """Build a label→value map, suffixing repeated labels when needed."""
+    counts: dict[str, int] = {}
+    options: dict[str, str] = {}
+    for label, value in pairs:
+        count = counts.get(label, 0)
+        counts[label] = count + 1
+        if count == 0:
+            key = label
+        elif disambiguate is not None:
+            key = disambiguate(label, value, count)
+        else:
+            key = f"{label} ({count + 1})"
+        options[key] = value
+    return options
+
+
+def empty_dropdown(
+    *,
+    label: str,
+    message: str,
+    full_width: bool = True,
+):
+    return mo.ui.dropdown(
+        options={message: ""},
+        label=label,
+        full_width=full_width,
+    )
+
+
+def connection_options(conns: list[Any]) -> dict[str, str]:
+    pairs = [(str(c.name), str(c.id)) for c in conns]
+    return unique_label_options(
+        pairs,
+        disambiguate=lambda label, value, count: f"{label} ({value})",
+    )
+
+
+def connection_picker_from_connections(
+    conns: list[Any],
+    *,
+    label: str = "Connection",
+    full_width: bool = True,
+):
+    if not conns:
+        return empty_dropdown(
+            label=label,
+            message="(no connections)",
+            full_width=full_width,
+        )
+    return mo.ui.dropdown(
+        options=connection_options(conns),
+        label=label,
+        full_width=full_width,
+    )
+
+
+def connection_picker(
+    client: HotdataClient,
+    *,
+    label: str = "Connection",
+    full_width: bool = True,
+):
+    conns = client.connections().list_connections().connections
+    return connection_picker_from_connections(
+        conns,
+        label=label,
+        full_width=full_width,
+    )
+
+
+def resolve_connection_picker(
+    client: HotdataClient,
+    *,
+    label: str = "Connection",
+    full_width: bool = True,
+) -> tuple[Any | None, str | None]:
+    """Return ``(dropdown_or_none, implicit_connection_id)`` for table browsers."""
+    conns = client.connections().list_connections().connections
+    if not conns:
+        return None, ""
+    if len(conns) == 1:
+        return None, conns[0].id
+    return (
+        connection_picker_from_connections(
+            conns,
+            label=label,
+            full_width=full_width,
+        ),
+        None,
+    )