Skip to content

A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.

7.6 KB
Raw Blame
/* Copyright 2026 Marimo. All rights reserved. */

import { Provider, useAtomValue } from "jotai";
import { DatabaseZapIcon } from "lucide-react";
import type React from "react";
import { useEffect } from "react";
import { flushSync } from "react-dom";
import { createRoot } from "react-dom/client";
import { useLocale } from "react-aria";
import { ProtocolIcon } from "@/components/storage/components";
import { Badge } from "@/components/ui/badge";
import { cacheInfoAtom } from "@/core/cache/requests";
import { dataConnectionsMapAtom } from "@/core/datasets/data-source-connections";
import type { ConnectionName } from "@/core/datasets/engines";
import { datasetTablesAtom } from "@/core/datasets/state";
import { getRequestClient } from "@/core/network/requests";
import { store } from "@/core/state/jotai";
import { storageNamespacesAtom } from "@/core/storage/state";
import { variablesAtom } from "@/core/variables/state";
import type { VariableName } from "@/core/variables/types";
import { assertNever } from "@/utils/assertNever";
import { formatTime } from "@/utils/formatting";
import { prettyNumber } from "@/utils/numbers";
import {
  CONTAINER_STYLES,
  MetadataRow,
  renderDatasourceInfo,
  renderEmptyInfo,
  renderTableInfo,
  SectionHeader,
} from "../language/languages/sql/renderers";
import type { CodeLensSpec } from "./entities";

/**
 * Mounts the hover popover for a code lens into `dom`; returns a dispose
 * function.
 */
export function mountLensPopover(
  dom: HTMLElement,
  spec: CodeLensSpec,
): () => void {
  const root = createRoot(dom);
  // CodeMirror measures and positions the tooltip as soon as this function
  // returns. Render now so it measures the popover content, not an empty
  // container that later grows over the hovered icon.
  flushSync(() => {
    root.render(
      <Provider store={store}>
        <LensPopover spec={spec} />
      </Provider>,
    );
  });
  // Defer so tearing the tooltip down from inside a React event (e.g. the
  // icon's click handler) doesn't unmount mid-render
  return () => queueMicrotask(() => root.unmount());
}

const LensPopover: React.FC<{ spec: CodeLensSpec }> = ({ spec }) => {
  switch (spec.kind) {
    case "table":
      return <TablePopover name={spec.name} />;
    case "connection":
      return <ConnectionPopover name={spec.name} />;
    case "bucket":
      return <BucketPopover name={spec.name} />;
    case "cache":
      return (
        <CachePopover
          boundName={spec.cache?.boundName ?? null}
          cacheName={spec.cache?.cacheName ?? null}
        />
      );
    default:
      assertNever(spec.kind);
  }
};

const TablePopover: React.FC<{ name: string }> = ({ name }) => {
  const tables = useAtomValue(datasetTablesAtom);
  const table = tables.find((t) => t.variable_name === name);
  return table ? renderTableInfo(table) : renderEmptyInfo("table");
};

const ConnectionPopover: React.FC<{ name: string }> = ({ name }) => {
  const connections = useAtomValue(dataConnectionsMapAtom);
  const connection = connections.get(name as ConnectionName);
  if (!connection) {
    return renderEmptyInfo("database");
  }
  return renderDatasourceInfo(connection);
};

const BucketPopover: React.FC<{ name: string }> = ({ name }) => {
  const namespaces = useAtomValue(storageNamespacesAtom);
  const namespace = namespaces.find((ns) => ns.name === name);
  if (!namespace) {
    return (
      <div className={CONTAINER_STYLES}>
        <span className="text-xs text-(--slate-11)">
          No storage information available.
        </span>
      </div>
    );
  }
  return (
    <div className={CONTAINER_STYLES}>
      <SectionHeader
        icon={
          <ProtocolIcon protocol={namespace.protocol} className="w-4 h-4" />
        }
        title={namespace.displayName}
        badge={
          <Badge variant="outline" className="text-xs">
            {namespace.protocol}
          </Badge>
        }
      />
      <div className="flex flex-col gap-2 py-2">
        <MetadataRow
          label="Variable"
          value={
            <code className="text-xs bg-(--slate-4) px-1 rounded">
              {namespace.name}
            </code>
          }
        />
        <MetadataRow
          label="Root"
          value={
            <code className="text-xs bg-(--slate-4) px-1 rounded">
              {namespace.rootPath || "(root)"}
            </code>
          }
        />
        <MetadataRow
          label="Backend"
          value={<span className="font-medium">{namespace.backendType}</span>}
        />
      </div>
    </div>
  );
};

// `_cache_call.__repr__` starts with "hits=N misses=N", which survives the
// variable-preview truncation
const CACHE_STATS_PATTERN = /\bhits=(\d+) misses=(\d+)/;

// The popover remounts on every hover (see `mountLensPopover`), so this has
// to live at module scope rather than in component state: it debounces the
// notebook-wide `getCacheInfo` fetch across repeated hovers.
let lastCacheInfoFetchAt: number | null = null;
const CACHE_INFO_REFETCH_INTERVAL_MS = 5000;

function maybeFetchCacheInfo(): void {
  const now = Date.now();
  if (
    lastCacheInfoFetchAt != null &&
    now - lastCacheInfoFetchAt < CACHE_INFO_REFETCH_INTERVAL_MS
  ) {
    return;
  }
  lastCacheInfoFetchAt = now;
  getRequestClient()
    .getCacheInfo()
    .catch(() => {
      // Allow the next hover to retry rather than waiting out the interval.
      lastCacheInfoFetchAt = null;
    });
}

const CachePopover: React.FC<{
  boundName: string | null;
  cacheName: string | null;
}> = ({ boundName, cacheName }) => {
  const { locale } = useLocale();
  const variables = useAtomValue(variablesAtom);
  const cacheInfo = useAtomValue(cacheInfoAtom);

  const variable = boundName ? variables[boundName as VariableName] : undefined;
  const stats = variable?.dataType?.startsWith("_cache_call")
    ? variable.value?.match(CACHE_STATS_PATTERN)
    : undefined;
  const hasLocalStats = Boolean(stats);

  // Only fetch the notebook-wide fallback when there are no per-cache stats
  // to show, and throttle across repeated hovers so mousing over a lens
  // several times in a row doesn't fire a fresh request every time.
  useEffect(() => {
    if (hasLocalStats) {
      return;
    }
    maybeFetchCacheInfo();
  }, [hasLocalStats]);

  return (
    <div className={CONTAINER_STYLES}>
      <SectionHeader
        icon={<DatabaseZapIcon className="w-4 h-4 text-(--amber-9)" />}
        title={cacheName ?? boundName ?? "Cache"}
      />
      {stats ? (
        <div className="flex flex-col gap-2 py-2">
          <MetadataRow
            label="Hits"
            value={
              <span className="font-medium">
                {prettyNumber(Number(stats[1]), locale)}
              </span>
            }
          />
          <MetadataRow
            label="Misses"
            value={
              <span className="font-medium">
                {prettyNumber(Number(stats[2]), locale)}
              </span>
            }
          />
        </div>
      ) : (
        cacheInfo && (
          <div className="flex flex-col gap-2 py-2">
            <span className="text-xs font-medium text-(--slate-11)">
              Notebook-wide
            </span>
            <MetadataRow
              label="Hits"
              value={prettyNumber(cacheInfo.hits, locale)}
            />
            <MetadataRow
              label="Misses"
              value={prettyNumber(cacheInfo.misses, locale)}
            />
            <MetadataRow
              label="Time saved"
              value={formatTime(cacheInfo.time, locale)}
            />
          </div>
        )
      )}
      <div className="pt-2 text-xs text-(--slate-10)">
        Click to open the cache panel
      </div>
    </div>
  );
};