@marimo-team/frontend 0.14.18-dev9 → 0.15.1-dev10

package/src/plugins/impl/vega/make-selectable.ts

@@ -0,0 +1,248 @@
+/* Copyright 2024 Marimo. All rights reserved. */
+
+import { findEncodedFields, makeEncodingInteractive } from "./encodings";
+import { Marks } from "./marks";
+import { Params } from "./params";
+import type {
+  GenericVegaSpec,
+  Mark,
+  SelectionType,
+  VegaLiteSpec,
+  VegaLiteUnitSpec,
+} from "./types";
+
+export function makeSelectable<T extends VegaLiteSpec>(
+  spec: T,
+  opts: {
+    chartSelection?: boolean | "interval" | "point";
+    fieldSelection?: boolean | string[];
+  },
+): T {
+  // Both default to true
+  let { chartSelection = true, fieldSelection = true } = opts;
+
+  // Disable selection if both are false
+  if (!chartSelection && !fieldSelection) {
+    return spec;
+  }
+
+  // If params already exist, we don't add any more
+  const hasLegendParam = spec.params?.some((param) => param.bind === "legend");
+  if (hasLegendParam) {
+    fieldSelection = false;
+  }
+  const hasChartParam = spec.params?.some((param) => !param.bind);
+  if (hasChartParam) {
+    chartSelection = false;
+  }
+
+  if ("vconcat" in spec) {
+    const subSpecs = spec.vconcat.map((subSpec) =>
+      "mark" in subSpec ? makeChartInteractive(subSpec) : subSpec,
+    );
+    // No pan/zoom for vconcat
+    return { ...spec, vconcat: subSpecs };
+  }
+
+  if ("hconcat" in spec) {
+    const subSpecs = spec.hconcat.map((subSpec) =>
+      "mark" in subSpec ? makeChartInteractive(subSpec) : subSpec,
+    );
+    // No pan/zoom for hconcat
+    return { ...spec, hconcat: subSpecs };
+  }
+
+  if ("layer" in spec) {
+    const subSpecs = spec.layer.map((subSpec, idx) => {
+      if (!("mark" in subSpec)) {
+        return subSpec;
+      }
+      let resolvedSpec = subSpec as VegaLiteUnitSpec;
+      resolvedSpec = makeChartSelectable(resolvedSpec, chartSelection, idx);
+      resolvedSpec = makeChartInteractive(resolvedSpec);
+      if (idx === 0) {
+        resolvedSpec = makeChartPanZoom(resolvedSpec);
+      }
+      return resolvedSpec;
+    });
+    return { ...spec, layer: subSpecs };
+  }
+
+  if (!("mark" in spec)) {
+    return spec;
+  }
+  // error, errorbar, boxplot are not interactive
+  if (!Marks.isInteractive(spec.mark)) {
+    return spec;
+  }
+
+  let resolvedSpec: VegaLiteUnitSpec = spec;
+  resolvedSpec = makeLegendSelectable(resolvedSpec, fieldSelection);
+  resolvedSpec = makeChartSelectable(resolvedSpec, chartSelection, undefined);
+  resolvedSpec = makeChartInteractive(resolvedSpec);
+  resolvedSpec = makeChartPanZoom(resolvedSpec);
+
+  return resolvedSpec as T;
+}
+
+/**
+ * Given a spec, add the necessary parameters to make the legend selectable.
+ */
+function makeLegendSelectable(
+  spec: VegaLiteUnitSpec,
+  fieldSelection: boolean | string[],
+): VegaLiteUnitSpec {
+  // If fieldSelection is false, we don't do anything
+  if (fieldSelection === false) {
+    return spec;
+  }
+
+  let legendFields = findEncodedFields(spec);
+  // If fieldSelection is an array, we filter the fields
+  if (Array.isArray(fieldSelection)) {
+    legendFields = legendFields.filter((field) =>
+      fieldSelection.includes(field),
+    );
+  }
+
+  const legendParams = legendFields.map((field) => Params.legend(field));
+  const nextParams = [...(spec.params || []), ...legendParams];
+
+  return {
+    ...spec,
+    params: nextParams,
+  } as VegaLiteUnitSpec;
+}
+
+/**
+ * Given a spec, add the necessary parameters to make the chart selectable.
+ *
+ * Not supported marks:
+ * - geoshape
+ * - text
+ */
+function makeChartSelectable(
+  spec: VegaLiteUnitSpec,
+  chartSelection: boolean | "interval" | "point",
+  /**
+   * If the spec is part of a layer, we need to know the layer number.
+   * This is so we can give unique names to the parameters.
+   */
+  layerNum: number | undefined,
+): VegaLiteUnitSpec {
+  // If chartSelection is false, we don't do anything
+  if (chartSelection === false) {
+    return spec;
+  }
+
+  let mark: Mark;
+  try {
+    mark = Marks.getMarkType(spec.mark);
+  } catch {
+    return spec;
+  }
+
+  // We don't do anything if the mark is geoshape
+  if (mark === "geoshape") {
+    return spec;
+  }
+
+  const resolvedChartSelection =
+    chartSelection === true ? getBestSelectionForMark(mark) : [chartSelection];
+
+  if (!resolvedChartSelection) {
+    return spec;
+  }
+
+  const params = resolvedChartSelection.map((selectionType) =>
+    selectionType === "interval"
+      ? Params.interval(spec, layerNum)
+      : Params.point(spec, layerNum),
+  );
+
+  const nextParams = [...(spec.params || []), ...params];
+
+  return {
+    ...spec,
+    params: nextParams,
+  } as VegaLiteUnitSpec;
+}
+
+/**
+ * Given a spec, add the necessary parameters to make the chart pan/zoomable.
+ *
+ * Not supported marks:
+ * - geoshape
+ */
+function makeChartPanZoom(spec: VegaLiteUnitSpec): VegaLiteUnitSpec {
+  let mark: Mark | undefined;
+  try {
+    mark = Marks.getMarkType(spec.mark);
+  } catch {
+    // noop
+  }
+
+  // We don't do anything if the mark is geoshape
+  if (mark === "geoshape") {
+    return spec;
+  }
+
+  const params = spec.params || [];
+
+  const alreadyHasScalesParam = params.some((param) => param.bind === "scales");
+  if (alreadyHasScalesParam) {
+    return spec;
+  }
+
+  return {
+    ...spec,
+    params: [...params, Params.panZoom()],
+  };
+}
+
+/**
+ * Makes a chart clickable and adds an opacity encoding to the chart.
+ *
+ * Not supported marks:
+ * - text
+ */
+function makeChartInteractive<T extends GenericVegaSpec>(spec: T): T {
+  const prevEncodings = "encoding" in spec ? spec.encoding : undefined;
+  const params = spec.params || [];
+  const paramNames = params.map((param) => param.name);
+
+  if (params.length === 0) {
+    return spec;
+  }
+
+  if (!Marks.isInteractive(spec.mark)) {
+    return spec;
+  }
+
+  return {
+    ...spec,
+    mark: Marks.makeClickable(spec.mark),
+    encoding: makeEncodingInteractive(
+      "opacity",
+      prevEncodings || {},
+      paramNames,
+      spec.mark,
+    ),
+  };
+}
+
+function getBestSelectionForMark(mark: Mark): SelectionType[] | undefined {
+  switch (mark) {
+    case "arc":
+    case "area":
+      return ["point"];
+    case "text":
+    case "bar":
+      return ["point", "interval"];
+    // there is no best selection for line
+    case "line":
+      return undefined;
+    default:
+      return ["point", "interval"];
+  }
+}

package/src/plugins/impl/vega/marks.ts

@@ -0,0 +1,36 @@
+/* Copyright 2024 Marimo. All rights reserved. */
+import { type AnyMark, Mark } from "./types";
+
+const NON_INTERACTIVE_MARKS = new Set(["boxplot", "errorband", "errorbar"]);
+
+export const Marks = {
+  getMarkType(mark: AnyMark): Mark {
+    const type = typeof mark === "string" ? mark : mark.type;
+    if (NON_INTERACTIVE_MARKS.has(type)) {
+      throw new Error("Not supported");
+    }
+    return type as Mark;
+  },
+  isInteractive(mark: AnyMark): boolean {
+    const type = typeof mark === "string" ? mark : mark.type;
+    return !NON_INTERACTIVE_MARKS.has(type);
+  },
+  makeClickable(mark: AnyMark): AnyMark {
+    const type = typeof mark === "string" ? mark : mark.type;
+    if (type in Mark) {
+      return typeof mark === "string"
+        ? { type: mark, cursor: "pointer", tooltip: true }
+        : ({ ...mark, type, cursor: "pointer", tooltip: true } as AnyMark);
+    }
+    return mark;
+  },
+  getOpacity(mark: AnyMark): number | null {
+    if (typeof mark === "string") {
+      return null;
+    }
+    if ("opacity" in mark && typeof mark.opacity === "number") {
+      return mark.opacity;
+    }
+    return null;
+  },
+};

package/src/plugins/impl/vega/params.ts

@@ -0,0 +1,192 @@
+/* Copyright 2024 Marimo. All rights reserved. */
+import type { TopLevelSpec } from "vega-lite";
+import type { LayerSpec, UnitSpec } from "vega-lite/build/src/spec";
+import { Marks } from "./marks";
+import {
+  type Field,
+  Mark,
+  type SelectionParameter,
+  type SingleDefUnitChannel,
+  type VegaLiteUnitSpec,
+} from "./types";
+
+export const ParamNames = {
+  point(layerNum: number | undefined) {
+    return layerNum == null ? "select_point" : `select_point_${layerNum}`;
+  },
+  interval(layerNum: number | undefined) {
+    return layerNum == null ? "select_interval" : `select_interval_${layerNum}`;
+  },
+  legendSelection(field: string) {
+    return `legend_selection_${field}`;
+  },
+  HIGHLIGHT: "highlight",
+  PAN_ZOOM: "pan_zoom",
+  hasPoint(names: string[]) {
+    return names.some((name) => name.startsWith("select_point"));
+  },
+  hasInterval(names: string[]) {
+    return names.some((name) => name.startsWith("select_interval"));
+  },
+  hasLegend(names: string[]) {
+    return names.some((name) => name.startsWith("legend_selection"));
+  },
+  hasPanZoom(names: string[]) {
+    return names.some((name) => name.startsWith("pan_zoom"));
+  },
+};
+
+export const Params = {
+  highlight() {
+    return {
+      name: ParamNames.HIGHLIGHT,
+      select: { type: "point", on: "mouseover" },
+    };
+  },
+  interval(
+    spec: VegaLiteUnitSpec,
+    layerNum: number | undefined,
+  ): SelectionParameter<"interval"> {
+    return {
+      name: ParamNames.interval(layerNum),
+      select: {
+        type: "interval",
+        encodings: getEncodingAxisForMark(spec),
+        mark: {
+          fill: "#669EFF",
+          fillOpacity: 0.07,
+          stroke: "#669EFF",
+          strokeOpacity: 0.4,
+        },
+        // So this does not conflict with pan/zoom via metaKey
+        on: "[mousedown[!event.metaKey], mouseup] > mousemove[!event.metaKey]",
+        translate:
+          "[mousedown[!event.metaKey], mouseup] > mousemove[!event.metaKey]",
+      },
+    };
+  },
+  point(
+    spec: VegaLiteUnitSpec,
+    layerNum: number | undefined,
+  ): SelectionParameter<"point"> {
+    return {
+      name: ParamNames.point(layerNum),
+      select: {
+        type: "point",
+        encodings: getEncodingAxisForMark(spec),
+        on: "click[!event.metaKey]",
+      },
+    };
+  },
+  legend(field: string): SelectionParameter<"point"> {
+    return {
+      name: ParamNames.legendSelection(field),
+      select: {
+        type: "point",
+        fields: [field],
+      },
+      bind: "legend",
+    };
+  },
+  panZoom(): SelectionParameter<"interval"> {
+    return {
+      name: ParamNames.PAN_ZOOM,
+      bind: "scales",
+      select: {
+        type: "interval",
+        on: "[mousedown[event.metaKey], window:mouseup] > window:mousemove!",
+        translate:
+          "[mousedown[event.metaKey], window:mouseup] > window:mousemove!",
+        zoom: "wheel![event.metaKey]",
+      },
+    };
+  },
+};
+
+export function getEncodingAxisForMark(
+  spec: VegaLiteUnitSpec,
+): SingleDefUnitChannel[] | undefined {
+  const mark = Marks.getMarkType(spec.mark);
+  switch (mark) {
+    case Mark.image:
+    case Mark.trail:
+      return undefined;
+    case Mark.area:
+    case Mark.arc:
+      return ["color"];
+    case Mark.bar: {
+      const direction = getDirectionOfBar(spec);
+      return direction === "horizontal"
+        ? ["y"]
+        : direction === "vertical"
+          ? ["x"]
+          : undefined;
+    }
+    case Mark.circle:
+    case Mark.geoshape:
+    case Mark.line:
+    case Mark.point:
+    case Mark.rect:
+    case Mark.rule:
+    case Mark.square:
+    case Mark.text:
+    case Mark.tick:
+      return ["x", "y"];
+  }
+}
+
+export function getSelectionParamNames(
+  spec: TopLevelSpec | LayerSpec<Field> | UnitSpec<Field>,
+): string[] {
+  if ("params" in spec && spec.params && spec.params.length > 0) {
+    const params = spec.params;
+    return (
+      params
+        // @ts-expect-error TS doesn't know that `param` is an object
+        .filter((param) => {
+          if (param == null) {
+            return false;
+          }
+          // @ts-expect-error TS doesn't know that `param` is an object
+          return "select" in param && param.select !== undefined;
+        })
+        .map((param) => param.name)
+    );
+  }
+  if ("layer" in spec) {
+    return [...new Set(spec.layer.flatMap(getSelectionParamNames))];
+  }
+  return [];
+}
+
+/**
+ * Returns the direction of the bar chart.
+ */
+export function getDirectionOfBar(
+  spec: VegaLiteUnitSpec,
+): "horizontal" | "vertical" | undefined {
+  if (!spec || !("mark" in spec)) {
+    return undefined;
+  }
+
+  const xEncoding = spec.encoding?.x;
+  const yEncoding = spec.encoding?.y;
+
+  if (xEncoding && "type" in xEncoding && xEncoding.type === "nominal") {
+    return "vertical";
+  }
+
+  if (yEncoding && "type" in yEncoding && yEncoding.type === "nominal") {
+    return "horizontal";
+  }
+
+  if (xEncoding && "aggregate" in xEncoding) {
+    return "horizontal";
+  }
+
+  if (yEncoding && "aggregate" in yEncoding) {
+    return "vertical";
+  }
+
+  return undefined;
+}

package/src/plugins/impl/vega/resolve-data.ts

@@ -0,0 +1,101 @@
+/* Copyright 2024 Marimo. All rights reserved. */
+
+import { asRemoteURL } from "@/core/runtime/config";
+import { vegaLoadData } from "./loader";
+import type {
+  FacetedUnitSpec,
+  Field,
+  GenericFacetSpec,
+  LayerSpec,
+  UnitSpec,
+  VegaLiteSpec,
+} from "./types";
+
+type AnySpec =
+  | VegaLiteSpec
+  | LayerSpec<Field>
+  | UnitSpec<Field>
+  | GenericFacetSpec<FacetedUnitSpec<Field>, LayerSpec<Field>, Field>;
+
+/**
+ * Given a VegaLite spec with URL data, resolve the data and return a new spec with the resolved data.
+ *
+ * This handles top-level URL data, as well as nested URL data in layers.
+ */
+export async function resolveVegaSpecData(
+  spec: VegaLiteSpec,
+): Promise<VegaLiteSpec> {
+  if (!spec) {
+    return spec;
+  }
+
+  const datasets = "datasets" in spec ? { ...spec.datasets } : {};
+
+  const traverse = async <T extends AnySpec>(spec: T): Promise<T> => {
+    if (!spec) {
+      return spec;
+    }
+
+    if ("layer" in spec) {
+      const layers = await Promise.all(spec.layer.map(traverse));
+      spec = {
+        ...spec,
+        layer: layers,
+      };
+    }
+    if ("hconcat" in spec) {
+      const hconcat = await Promise.all(spec.hconcat.map(traverse));
+      spec = {
+        ...spec,
+        hconcat,
+      };
+    }
+    if ("vconcat" in spec) {
+      const vconcat = await Promise.all(spec.vconcat.map(traverse));
+      spec = {
+        ...spec,
+        vconcat,
+      };
+    }
+
+    if ("spec" in spec) {
+      spec = {
+        ...spec,
+        spec: await traverse(spec.spec),
+      };
+    }
+
+    if (!spec.data) {
+      return spec;
+    }
+
+    if (!("url" in spec.data)) {
+      return spec;
+    }
+
+    // Parse URL
+    let url: URL;
+    try {
+      url = asRemoteURL(spec.data.url);
+    } catch {
+      return spec;
+    }
+    const data = await vegaLoadData(url.href, spec.data.format);
+
+    datasets[url.pathname] = data;
+
+    return {
+      ...spec,
+      data: { name: url.pathname },
+    };
+  };
+
+  const resolvedSpec = await traverse(spec);
+  if (Object.keys(datasets).length === 0) {
+    return resolvedSpec;
+  }
+  return {
+    ...resolvedSpec,
+    datasets,
+  };
+}

package/src/plugins/impl/vega/types.ts

@@ -0,0 +1,32 @@
+/* Copyright 2024 Marimo. All rights reserved. */
+
+import type { Field } from "vega-lite/build/src/channeldef";
+import type { Encoding } from "vega-lite/build/src/encoding";
+import type {
+  GenericUnitSpec,
+  TopLevelUnitSpec,
+} from "vega-lite/build/src/spec/unit";
+
+export type { TopLevelSpec as VegaLiteSpec } from "vega-lite";
+export type { SingleDefUnitChannel } from "vega-lite/build/src/channel";
+export type { Field } from "vega-lite/build/src/channeldef";
+export type { SharedCompositeEncoding } from "vega-lite/build/src/compositemark";
+export type { DataFormat } from "vega-lite/build/src/data";
+export type { AnyMark, MarkDef } from "vega-lite/build/src/mark";
+export { Mark } from "vega-lite/build/src/mark";
+export type {
+  SelectionParameter,
+  SelectionType,
+} from "vega-lite/build/src/selection";
+export type {
+  FacetedUnitSpec,
+  GenericFacetSpec,
+  LayerSpec,
+  UnitSpec,
+} from "vega-lite/build/src/spec";
+
+export type VegaLiteUnitSpec = TopLevelUnitSpec<Field>;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type GenericVegaSpec = GenericUnitSpec<any, any, any>;
+export type EncodingType = keyof Encoding<Field>;
+export type Encodings = Encoding<Field>;

package/src/plugins/impl/vega/utils.ts

@@ -0,0 +1,46 @@
+/* Copyright 2024 Marimo. All rights reserved. */
+
+import { Objects } from "@/utils/objects";
+import type { DataType, FieldTypes, VegaDataType } from "./vega-loader";
+
+export function mergeAsArrays<T>(
+  left: T | T[] | undefined,
+  right: T | T[] | undefined,
+): T[] {
+  return [...toArray(left), ...toArray(right)];
+}
+
+function toArray<T>(value: T | T[] | undefined): T[] {
+  if (!value) {
+    return [];
+  }
+  if (Array.isArray(value)) {
+    return value;
+  }
+  return [value];
+}
+
+export function getVegaFieldTypes(
+  types: Record<string, DataType> | undefined | null,
+): FieldTypes | "auto" {
+  if (!types || Object.keys(types).length === 0) {
+    // If fieldTypes is provided, use it to parse the data
+    // Otherwise, infer the data types
+    return "auto";
+  }
+  // Convert all 'date' to 'string', because dates don't format back to
+  // the correct formatting. For example, a date like '2024-01-01' will
+  // be formatted to '2024-01-01T00:00:00.000Z'.
+  return Objects.mapValues(types, (type): VegaDataType => {
+    if (type === "date") {
+      return "string";
+    }
+    if (type === "time") {
+      return "string";
+    }
+    if (type === "datetime") {
+      return "date";
+    }
+    return type;
+  });
+}