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.

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

import type { Table } from "@tanstack/react-table";
import type { TableData } from "@/plugins/impl/DataTablePlugin";
import { vegaLoadData } from "@/plugins/impl/vega/loader";
import { jsonParseWithSpecialChar } from "@/utils/json/json-parser";
import { isRecord } from "@/utils/records";
import { getMimeValues } from "./mime-cell";
import type { DataType } from "@/core/kernel/messages";
import {
  type CellValueSentinel,
  INDEX_COLUMN_NAME,
  isNumericType,
  isTemporalType,
} from "./types";

const WHITESPACE_ONLY_RE = /^[\s]+$/;
const WHITESPACE_CHAR_RE = /\s/;
const EDGE_WHITESPACE_RE = /^(\s*)([\s\S]*?)(\s*)$/;

/**
 * checks for leading and trailing whitespaces.
 * Will run for every cell, so fast exits for common cases
 *
 * @param value - to split
 * @returns - leading, middle, and trailing string where leading and trailing are whitespace string
 */
export function splitLeadingTrailingWhitespace(value: string): {
  leading: string;
  middle: string;
  trailing: string;
} {
  const parts = {
    leading: "",
    middle: "",
    trailing: "",
  };
  if (value.length === 0) {
    return parts;
  }

  const firstWhitespaceCh = WHITESPACE_CHAR_RE.test(value[0]);
  const lastWhitespaceCh = WHITESPACE_CHAR_RE.test(value[value.length - 1]);

  // if does not start or end with ws
  if (!firstWhitespaceCh && !lastWhitespaceCh) {
    parts.middle = value;
    return parts;
  }

  const match = EDGE_WHITESPACE_RE.exec(value);
  if (!match) {
    parts.middle = value;
    return parts;
  }

  parts.leading = match[1] ?? "";
  parts.middle = match[2] ?? "";
  parts.trailing = match[3] ?? "";

  return parts;
}

/**
 * Convenience function to load table data.
 *
 * This resolves to an array of objects, where each object represents a row.
 */
export async function loadTableData<T = object>(
  tableData: TableData<T>,
): Promise<T[]> {
  // If we already have the data, return it
  if (Array.isArray(tableData)) {
    return tableData;
  }

  // If it looks like json, parse it
  if (tableData.startsWith("{") || tableData.startsWith("[")) {
    return jsonParseWithSpecialChar(tableData);
  }

  // Otherwise, load the data from the URL
  tableData = await vegaLoadData(
    tableData,
    { type: "json" },
    { handleBigIntAndNumberLike: true },
  );
  return tableData;
}

/**
 * Load both table and raw table data. Raw table data is typically when
 * there is formatting applied to the table data.
 */
export async function loadTableAndRawData<T>(
  tableData: TableData<T>,
  rawTableData?: TableData<T> | null,
): Promise<[T[], T[] | undefined]> {
  if (rawTableData) {
    return Promise.all([loadTableData(tableData), loadTableData(rawTableData)]);
  }

  return [await loadTableData(tableData), undefined];
}

/**
 * Get the stable row ID for a row.
 *
 * This is the row ID that is used to identify a row in the table.
 * It is stable across renders and pagination. It may not exist.
 *
 */
export function getStableRowId<TData>(row: TData): string | undefined {
  if (row && typeof row === "object" && INDEX_COLUMN_NAME in row) {
    return String(row[INDEX_COLUMN_NAME]);
  }
}

/**
 * Calculate which page a given row index should be on.
 *
 * @param rowIdx - The row index to check
 * @param currentPageIndex - The current page index
 * @param pageSize - The number of rows per page
 * @returns The page index if pagination should change, or null if the row is on the current page
 */
export function getPageIndexForRow(
  rowIdx: number,
  currentPageIndex: number,
  pageSize: number,
): number | null {
  const currentPageStart = currentPageIndex * pageSize;
  const currentPageEnd = currentPageStart + pageSize - 1;

  if (rowIdx < currentPageStart || rowIdx > currentPageEnd) {
    return Math.floor(rowIdx / pageSize);
  }

  return null;
}

// String representations of numeric special values.
// Only matched when the caller indicates the column is numeric.
type StringValueSentinelType = Extract<
  CellValueSentinel,
  { value: number | string }
>["type"];

const NUMERIC_STRING_SPECIALS: Record<string, StringValueSentinelType> = {
  NaN: "nan",
  Infinity: "positive-infinity",
  "-Infinity": "negative-infinity",
  inf: "positive-infinity",
  "-inf": "negative-infinity",
};

// These source-library dtypes are temporal, but their normalized marimo data
// types are "string", "number", or "unknown" instead of a temporal type.
const NAT_DTYPE_PREFIXES = ["timedelta64[", "period[", "duration"] as const;

function isNaTType(
  dataType: DataType | undefined,
  dtype: string | undefined,
): boolean {
  if (isTemporalType(dataType)) {
    return true;
  }
  if (!dtype) {
    return false;
  }

  const normalizedDtype = dtype.toLowerCase();
  return NAT_DTYPE_PREFIXES.some((prefix) =>
    normalizedDtype.startsWith(prefix),
  );
}

/**
 * Detect if a cell value is a sentinel (null, empty string, whitespace,
 * NaN, infinity, NaT). Column-type-dependent sentinels (string "NaN",
 * "NaT", etc.) are matched based on `dataType` and `dtype`.
 *
 * `dataType` is marimo's normalized, backend-independent type. `dtype` is
 * the source library's more specific type string.
 */
export function detectSentinel(
  value: unknown,
  dataType: DataType | undefined,
  dtype?: string,
): CellValueSentinel | null {
  if (value == null) {
    return { type: "null", value };
  }

  if (typeof value === "string") {
    if (value === "") {
      return { type: "empty-string", value };
    }
    if (WHITESPACE_ONLY_RE.test(value)) {
      return { type: "whitespace", value };
    }
    // String "NaN"/"Infinity" in a numeric column = actual special float value
    if (isNumericType(dataType)) {
      const type = NUMERIC_STRING_SPECIALS[value];
      if (type) {
        return { type, value };
      }
    }
    if (value === "NaT" && isNaTType(dataType, dtype)) {
      return { type: "nat", value };
    }
    return null;
  }

  if (typeof value === "number") {
    if (Number.isNaN(value)) {
      return { type: "nan", value };
    }
    if (value === Number.POSITIVE_INFINITY) {
      return { type: "positive-infinity", value };
    }
    if (value === Number.NEGATIVE_INFINITY) {
      return { type: "negative-infinity", value };
    }
    return null;
  }

  return null;
}

type NullishSentinelType = Extract<CellValueSentinel["type"], "null" | "nat">;

const NULLISH_SENTINEL_TYPES: ReadonlySet<CellValueSentinel["type"]> =
  new Set<NullishSentinelType>(["null", "nat"]);

/**
 * True when the cell value represents a missing value (null, NaT)
 * rather than a real value that happens to look special.
 */
export function isNullishSentinel(
  value: unknown,
  dataType: DataType | undefined,
  dtype?: string,
): boolean {
  const sentinel = detectSentinel(value, dataType, dtype);
  return sentinel !== null && NULLISH_SENTINEL_TYPES.has(sentinel.type);
}

/**
 * Stringify an unknown value. Converts objects to JSON strings.
 * @param opts.value - The value to stringify.
 * @param opts.nullAsEmptyString - If true, null values will be "". Else, stringify.
 */
export function stringifyUnknownValue(opts: {
  value: unknown;
  nullAsEmptyString?: boolean;
}): string {
  const { value, nullAsEmptyString = false } = opts;

  if (typeof value === "object" && value !== null) {
    return JSON.stringify(value);
  }
  if (value === null && nullAsEmptyString) {
    return "";
  }
  return String(value);
}

function stripHtml(html: string): string {
  const div = document.createElement("div");
  div.innerHTML = html;
  const text = (div.textContent || div.innerText || "").trim();
  return text || html;
}

const HTML_MIMETYPES = new Set(["text/html", "text/markdown"]);

/**
 * Get clipboard-ready text and optional HTML for a cell.
 *
 * @param rawValue - The raw (unformatted) value, or undefined if not available.
 * @param displayedValue - The displayed value (may be a mime bundle).
 */
export function getClipboardContent(
  rawValue: unknown,
  displayedValue: unknown,
): { text: string; html?: string } {
  const mimeValues =
    typeof displayedValue === "object" && displayedValue !== null
      ? getMimeValues(displayedValue)
      : undefined;

  let html: string | undefined;
  if (mimeValues) {
    // text/markdown from mo.md() contains rendered HTML
    const htmlParts = mimeValues
      .filter((v) => HTML_MIMETYPES.has(v.mimetype))
      .map((v) => v.data);
    html = htmlParts.length > 0 ? htmlParts.join("") : undefined;
  }

  let text: string;
  if (rawValue !== undefined && rawValue !== displayedValue) {
    text = stringifyUnknownValue({ value: rawValue });
  } else if (mimeValues) {
    text = mimeValues
      .map((v) => (HTML_MIMETYPES.has(v.mimetype) ? stripHtml(v.data) : v.data))
      .join(", ");
  } else {
    text = stringifyUnknownValue({ value: displayedValue });
  }

  return { text, html };
}

/**
 * Get the raw (unformatted) value for a row/column from the table,
 * or undefined if raw data is not available.
 */
export function getRawValue<TData>(
  table: Table<TData>,
  rowIndex: number,
  columnId: string,
): unknown {
  const rawData = table.options.meta?.rawData;
  if (rawData) {
    const rawRow = rawData[rowIndex];
    if (isRecord(rawRow)) {
      return rawRow[columnId];
    }
  }
  return undefined;
}