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.
Python artificial-intelligencedagdata-sciencedata-visualizationdataflowdeveloper-toolsmachine-learningnotebookspipelinepythonreactivesqlweb-app
/* Copyright 2026 Marimo. All rights reserved. */
import { zodResolver } from "@hookform/resolvers/zod";
import { useAtom } from "jotai";
import {
AlertTriangle,
ChartColumnIcon,
ChevronLeftIcon,
ChevronRightIcon,
CodeIcon,
DatabaseIcon,
PaintRollerIcon,
XIcon,
} from "lucide-react";
import type { JSX } from "react";
import React, { useMemo, useState } from "react";
import { type UseFormReturn, useForm, useWatch } from "react-hook-form";
import useResizeObserver from "use-resize-observer";
import { PythonIcon } from "@/components/editor/cell/code/icons";
import { Alert, AlertDescription } from "@/components/ui/alert";
import { Button } from "@/components/ui/button";
import { Form } from "@/components/ui/form";
import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs";
import type { CellId } from "@/core/cells/ids";
import { useAsyncData } from "@/hooks/useAsyncData";
import { useDeepCompareMemoize } from "@/hooks/useDeepCompareMemoize";
import { useDebouncedCallback } from "@/hooks/useDebounce";
import type { GetDataUrl } from "@/plugins/impl/DataTablePlugin";
import { vegaLoadData } from "@/plugins/impl/vega/loader";
import { getVegaFieldTypes } from "@/plugins/impl/vega/utils";
import { useTheme } from "@/theme/useTheme";
import { uniqueBy } from "@/utils/arrays";
import { inferFieldTypes } from "../columns";
import {
type FieldTypesWithExternalType,
TOO_MANY_ROWS,
type TooManyRows,
} from "../types";
import { generateAltairChartSnippet } from "./chart-spec/altair-generator";
import { createSpecWithoutData } from "./chart-spec/spec";
import { ChartTypeSelect } from "./components/chart-items";
import { ChartErrorState, ChartLoadingState } from "./components/chart-states";
import type { Field } from "./components/form-fields";
import { CodeSnippet, TabContainer } from "./components/layouts";
import { ChartFormContext } from "./context";
import { CommonChartForm, StyleForm } from "./forms/common-chart";
import { HeatmapForm } from "./forms/heatmap";
import { PieForm } from "./forms/pie";
import { LazyChart } from "./lazy-chart";
import { ChartSchema, type ChartSchemaType, getChartDefaults } from "./schemas";
import {
createTabId,
getChartTabName,
type TabName,
tabsStorageAtom,
} from "./storage";
import { ChartType } from "./types";
const NEW_CHART_TYPE = "bar" as ChartType;
const DEFAULT_TAB_NAME = "table" as TabName;
const CHART_HEIGHT = 290;
const CHART_MAX_ROWS = 50_000;
const CHART_MAX_COLUMNS = 50;
/**
* Append row-header (index) fields to the chart field list, skipping any whose
* name already exists as a data column so the chart builder never offers the
* same axis twice.
*/
export function mergeIndexFields(
fieldTypes: FieldTypesWithExternalType | null | undefined,
rowHeaders: FieldTypesWithExternalType | null | undefined,
): FieldTypesWithExternalType {
const base = fieldTypes ?? [];
if (!rowHeaders || rowHeaders.length === 0) {
return base;
}
return uniqueBy([...base, ...rowHeaders], (f) => f[0]);
}
export interface TablePanelProps {
cellId: CellId | null;
data: unknown[];
dataTable: JSX.Element;
totalRows: number | TooManyRows;
columns: number;
displayHeader: boolean;
onCloseChartBuilder?: () => void;
getDataUrl?: GetDataUrl;
fieldTypes?: FieldTypesWithExternalType | null;
rowHeaders?: FieldTypesWithExternalType | null;
}
export const TablePanel: React.FC<TablePanelProps> = ({
cellId,
data,
dataTable,
totalRows,
columns,
getDataUrl,
fieldTypes,
rowHeaders,
displayHeader,
onCloseChartBuilder,
}) => {
const [tabsMap, saveTabsMap] = useAtom(tabsStorageAtom);
const tabs = cellId ? (tabsMap.get(cellId) ?? []) : [];
const [selectedTab, setSelectedTab] = useState(DEFAULT_TAB_NAME);
const [tabCounter, setTabCounter] = useState(tabs.length);
const [prevDisplayHeader, setPrevDisplayHeader] = useState(displayHeader);
if (displayHeader !== prevDisplayHeader) {
setPrevDisplayHeader(displayHeader);
}
// Auto-create a default chart tab when chart builder opens with no tabs
if (displayHeader && !prevDisplayHeader && tabs.length === 0 && cellId) {
const tabName = getChartTabName(0, NEW_CHART_TYPE);
const newTabs = new Map(tabsMap);
newTabs.set(cellId, [
{
id: createTabId(),
tabName,
chartType: NEW_CHART_TYPE,
config: getChartDefaults(),
},
]);
saveTabsMap(newTabs);
setTabCounter(1);
setSelectedTab(tabName);
}
if (!displayHeader || (tabs.length === 0 && !displayHeader)) {
return dataTable;
}
const handleAddTab = () => {
if (!cellId) {
return;
}
const tabName = getChartTabName(tabCounter, NEW_CHART_TYPE);
const newTabs = new Map(tabsMap);
newTabs.set(cellId, [
...tabs,
{
id: createTabId(),
tabName,
chartType: NEW_CHART_TYPE,
config: getChartDefaults(),
},
]);
saveTabsMap(newTabs);
setTabCounter(tabCounter + 1);
setSelectedTab(tabName);
};
const handleDeleteTab = (tabName: TabName) => {
if (!cellId) {
return;
}
const deletedIndex = tabs.findIndex((tab) => tab.tabName === tabName);
const remaining = tabs.filter((tab) => tab.tabName !== tabName);
const newTabs = new Map(tabsMap);
newTabs.set(cellId, remaining);
saveTabsMap(newTabs);
if (remaining.length === 0) {
onCloseChartBuilder?.();
} else if (tabName === selectedTab) {
if (deletedIndex < remaining.length) {
setSelectedTab(remaining[deletedIndex].tabName);
} else {
setSelectedTab(remaining[remaining.length - 1].tabName);
}
}
};
const saveTabChart = ({
tabName,
chartType,
chartConfig,
}: {
tabName: TabName;
chartType: ChartType;
chartConfig: ChartSchemaType;
}) => {
if (!cellId) {
return;
}
const updatedTabs = new Map(tabsMap);
updatedTabs.set(
cellId,
tabs.map((tab) =>
tab.tabName === tabName
? { ...tab, chartType, config: chartConfig }
: tab,
),
);
saveTabsMap(updatedTabs);
};
const saveTabChartType = (tabName: TabName, chartType: ChartType) => {
if (!cellId) {
return;
}
const tabs = tabsMap.get(cellId) ?? [];
const tabIndex = tabs.findIndex((tab) => tab.tabName === tabName);
if (tabIndex === -1) {
return;
}
const newTabs = tabs.map((tab) =>
tab.tabName === tabName
? {
...tab,
chartType,
tabName: getChartTabName(tabIndex, chartType),
}
: tab,
);
const newTabsMap = new Map(tabsMap).set(cellId, newTabs);
saveTabsMap(newTabsMap);
setSelectedTab(newTabs[tabIndex].tabName);
};
const isLargeDataset =
totalRows === TOO_MANY_ROWS ||
totalRows > CHART_MAX_ROWS ||
columns > CHART_MAX_COLUMNS;
return (
<Tabs value={selectedTab} className="-mt-1">
<TabsList part="table-tabs">
<TabsTrigger
className="text-xs"
value={DEFAULT_TAB_NAME}
onClick={() => setSelectedTab(DEFAULT_TAB_NAME)}
>
Table
</TabsTrigger>
{tabs.map((tab) => (
<TabsTrigger
key={tab.id}
className="text-xs"
value={tab.tabName}
onClick={() => setSelectedTab(tab.tabName)}
>
{tab.tabName}
<XIcon
className="w-3 h-3 ml-1 mt-[0.5px] hover:text-red-500 hover:font-semibold"
onClick={(e) => {
e.stopPropagation();
handleDeleteTab(tab.tabName);
}}
/>
</TabsTrigger>
))}
<Button
variant="text"
size="icon"
onClick={handleAddTab}
title="Add chart"
>
+
</Button>
</TabsList>
<TabsContent className="mt-1 overflow-hidden" value={DEFAULT_TAB_NAME}>
{dataTable}
</TabsContent>
{tabs.map((tab) => {
const saveChart = (formValues: ChartSchemaType) => {
saveTabChart({
tabName: tab.tabName,
chartType: tab.chartType,
chartConfig: formValues,
});
};
const saveChartType = (chartType: ChartType) => {
saveTabChartType(tab.tabName, chartType);
};
return (
<TabsContent
key={tab.id}
value={tab.tabName}
className="h-[400px] mt-0"
>
<ChartPanel
tableData={data}
chartConfig={tab.config}
chartType={tab.chartType}
saveChart={saveChart}
saveChartType={saveChartType}
getDataUrl={getDataUrl}
hasSchema={Boolean(fieldTypes?.length)}
fieldTypes={mergeIndexFields(
fieldTypes ?? inferFieldTypes(dataTable.props.data),
rowHeaders,
)}
isLargeDataset={isLargeDataset}
/>
</TabsContent>
);
})}
</Tabs>
);
};
const CHART_PLACEHOLDER_CODE = "X and Y columns are not set";
export const ChartPanel: React.FC<{
tableData: unknown[];
chartConfig: ChartSchemaType | null;
chartType: ChartType;
saveChart: (formValues: ChartSchemaType) => void;
saveChartType: (chartType: ChartType) => void;
getDataUrl?: GetDataUrl;
fieldTypes?: FieldTypesWithExternalType | null;
hasSchema?: boolean;
isLargeDataset: boolean;
}> = ({
tableData,
chartConfig,
chartType,
saveChart,
saveChartType,
getDataUrl,
fieldTypes,
hasSchema: providedHasSchema,
isLargeDataset,
}) => {
const hasSchema = providedHasSchema ?? Boolean(fieldTypes?.length);
const { theme } = useTheme();
const form = useForm<ChartSchemaType>({
defaultValues: chartConfig ?? getChartDefaults(),
resolver: zodResolver(ChartSchema),
});
const [selectedChartType, setSelectedChartType] =
useState<ChartType>(chartType);
const [formCollapsed, setFormCollapsed] = useState(false);
const [renderLargeCharts, setRenderLargeCharts] = useState(!isLargeDataset);
const { ref: chartContainerRef } = useResizeObserver();
// Sample-inferred types are useful for controls, but not full CSV parsing.
const csvFieldTypes = useDeepCompareMemoize(hasSchema ? fieldTypes : null);
const { data, isPending, error } = useAsyncData(async () => {
if (!getDataUrl || tableData.length === 0 || !renderLargeCharts) {
return [];
}
const response = await getDataUrl({});
if (Array.isArray(response.data_url)) {
return response.data_url;
}
let format: Parameters<typeof vegaLoadData>[1];
if (response.format === "arrow") {
format = { type: "arrow" };
} else if (response.format === "json") {
format = { type: "json" };
} else {
format = {
type: "csv",
parse: getVegaFieldTypes(
csvFieldTypes &&
Object.fromEntries(
csvFieldTypes.map(([name, [type]]) => [name, type]),
),
{ parseDates: true },
),
};
}
return vegaLoadData(response.data_url, format);
// Re-run when the data table changes
}, [tableData, renderLargeCharts, csvFieldTypes]);
// useWatch returns a new object only when a value changes. It is typed as
// deeply partial, but the form always starts from complete defaults.
const formValues = useWatch({ control: form.control }) as ChartSchemaType;
const specWithoutData = createSpecWithoutData({
chartType: selectedChartType,
formValues,
theme,
width: "container",
height: CHART_HEIGHT,
});
// Prevent unnecessary re-renders of the chart
const memoizedChart = useMemo(() => {
if (isPending) {
return <ChartLoadingState />;
}
if (error) {
return <ChartErrorState error={error} />;
}
if (!renderLargeCharts) {
return (
<Alert
variant="warning"
className="flex flex-row gap-2 items-center w-2/3 mx-auto"
>
<AlertTriangle className="h-4 w-4 mt-1" />
<AlertDescription className="flex flex-row justify-between items-center w-full">
<span>
Rendering large datasets is not well supported and may crash the
browser
</span>
<Button
variant="warn"
onClick={() => setRenderLargeCharts(true)}
className="h-8"
>
Proceed
</Button>
</AlertDescription>
</Alert>
);
}
return (
<LazyChart baseSpec={specWithoutData} data={data} height={CHART_HEIGHT} />
);
}, [isPending, error, renderLargeCharts, specWithoutData, data]);
const developmentMode = import.meta.env.DEV;
const renderChartDisplay = () => {
let altairCodeSnippet = CHART_PLACEHOLDER_CODE;
if (typeof specWithoutData !== "string") {
altairCodeSnippet = generateAltairChartSnippet(
specWithoutData,
"_df",
"_chart",
);
}
return (
<Tabs defaultValue="chart">
<div className="flex flex-row gap-1.5 items-center">
<TabsList>
<TabsTrigger value="chart" className="h-6">
<ChartColumnIcon className="text-muted-foreground mr-2 w-4 h-4" />
Chart
</TabsTrigger>
<TabsTrigger value="code" className="h-6">
<PythonIcon className="text-muted-foreground mr-2" />
Python code
</TabsTrigger>
{developmentMode && (
<>
<TabsTrigger value="formValues" className="h-6">
<CodeIcon className="text-muted-foreground mr-2 w-4 h-4" />
Form values (debug)
</TabsTrigger>
<TabsTrigger value="vegaSpec" className="h-6">
<CodeIcon className="text-muted-foreground mr-2 w-4 h-4" />
Vega spec (debug)
</TabsTrigger>
</>
)}
</TabsList>
</div>
<TabsContent value="chart" ref={chartContainerRef}>
{memoizedChart}
</TabsContent>
<TabsContent value="code">
<CodeSnippet
code={altairCodeSnippet}
insertNewCell={altairCodeSnippet !== CHART_PLACEHOLDER_CODE}
language="python"
/>
</TabsContent>
{developmentMode && (
<>
<TabsContent value="formValues">
<CodeSnippet
code={JSON.stringify(formValues, null, 2)}
language="python"
/>
</TabsContent>
<TabsContent value="vegaSpec">
<CodeSnippet
code={JSON.stringify(specWithoutData, null, 2)}
language="python"
/>
</TabsContent>
</>
)}
</Tabs>
);
};
const chartForm = (
<>
<ChartTypeSelect
value={selectedChartType}
onValueChange={(value) => {
setSelectedChartType(value);
saveChartType(value);
}}
/>
<ChartFormContainer
form={form}
saveChart={saveChart}
fieldTypes={fieldTypes}
chartType={selectedChartType}
/>
</>
);
return (
<div className="flex flex-row gap-2 h-full rounded-md border-t pr-2">
<div
className={`relative flex flex-col gap-2 overflow-auto px-2 py-3 scrollbar-thin transition-width duration-200 ${formCollapsed ? "w-8" : "w-[300px]"}`}
>
{!formCollapsed && chartForm}
<Button
variant="outline"
size="icon"
className="border-border ml-auto"
onClick={() => setFormCollapsed((prev) => !prev)}
title={formCollapsed ? "Expand sidebar" : "Collapse sidebar"}
>
{formCollapsed ? (
<ChevronRightIcon className="w-4 h-5" />
) : (
<ChevronLeftIcon className="w-4 h-5" />
)}
</Button>
</div>
<div className="flex-1 overflow-auto h-full w-full mt-3">
{renderChartDisplay()}
</div>
</div>
);
};
const ChartFormContainer = ({
form,
saveChart,
fieldTypes,
chartType,
}: {
form: UseFormReturn<ChartSchemaType>;
chartType: ChartType;
saveChart: (formValues: ChartSchemaType) => void;
fieldTypes?: FieldTypesWithExternalType | null;
}) => {
let fields: Field[] = [];
if (fieldTypes) {
fields = fieldTypes.map((field) => {
return {
name: field[0],
type: field[1][0],
};
});
}
const debouncedSave = useDebouncedCallback(() => {
const values = form.getValues();
saveChart(values);
}, 300);
let ChartForm = CommonChartForm;
if (chartType === ChartType.PIE) {
ChartForm = PieForm;
} else if (chartType === ChartType.HEATMAP) {
ChartForm = HeatmapForm;
}
return (
<ChartFormContext value={{ fields, saveForm: debouncedSave, chartType }}>
<Form {...form}>
<form onSubmit={(e) => e.preventDefault()} onChange={debouncedSave}>
<Tabs defaultValue="data">
<TabsList className="w-full">
<TabsTrigger value="data" className="w-1/2 h-6">
<DatabaseIcon className="w-4 h-4 mr-2" />
Data
</TabsTrigger>
<TabsTrigger value="style" className="w-1/2 h-6">
<PaintRollerIcon className="w-4 h-4 mr-2" />
Style
</TabsTrigger>
</TabsList>
<TabsContent value="data">
<hr className="my-2" />
<TabContainer>
<ChartForm />
</TabContainer>
</TabsContent>
<TabsContent value="style">
<hr className="my-2" />
<TabContainer>
<StyleForm />
</TabContainer>
</TabsContent>
</Tabs>
</form>
</Form>
</ChartFormContext>
);
};