@marimo-team/islands 0.17.2 → 0.17.3

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

@@ -1,6 +1,6 @@
 /* Copyright 2024 Marimo. All rights reserved. */
 import { describe, expect, it } from "vitest";
-import { getDirectionOfBar } from "../params";
+import { getBinnedFields, getDirectionOfBar, ParamNames } from "../params";
 import type { VegaLiteUnitSpec } from "../types";
 
 describe("getDirectionOfBar", () => {
@@ -50,3 +50,123 @@ describe("getDirectionOfBar", () => {
     expect(getDirectionOfBar(spec)).toBeUndefined();
   });
 });
+
+describe("getBinnedFields", () => {
+  it("should return empty array if spec has no encoding", () => {
+    const spec = { mark: "point" } as VegaLiteUnitSpec;
+    expect(getBinnedFields(spec)).toEqual([]);
+  });
+
+  it("should return empty array if no fields are binned", () => {
+    const spec = {
+      mark: "point",
+      encoding: {
+        x: { field: "x", type: "quantitative" },
+        y: { field: "y", type: "quantitative" },
+      },
+    } as VegaLiteUnitSpec;
+    expect(getBinnedFields(spec)).toEqual([]);
+  });
+
+  it("should return binned field name for x encoding", () => {
+    const spec = {
+      mark: "bar",
+      encoding: {
+        x: { field: "x", bin: true, type: "quantitative" },
+        y: { aggregate: "count", type: "quantitative" },
+      },
+    } as VegaLiteUnitSpec;
+    expect(getBinnedFields(spec)).toEqual(["x"]);
+  });
+
+  it("should return binned field name for y encoding", () => {
+    const spec = {
+      mark: "bar",
+      encoding: {
+        x: { aggregate: "count", type: "quantitative" },
+        y: { field: "y", bin: true, type: "quantitative" },
+      },
+    } as VegaLiteUnitSpec;
+    expect(getBinnedFields(spec)).toEqual(["y"]);
+  });
+
+  it("should return multiple binned fields", () => {
+    const spec = {
+      mark: "rect",
+      encoding: {
+        x: { field: "x", bin: true, type: "quantitative" },
+        y: { field: "y", bin: true, type: "quantitative" },
+        color: { aggregate: "count", type: "quantitative" },
+      },
+    } as VegaLiteUnitSpec;
+    expect(getBinnedFields(spec)).toEqual(["x", "y"]);
+  });
+
+  it("should handle bin with custom configuration", () => {
+    const spec = {
+      mark: "bar",
+      encoding: {
+        x: {
+          field: "temperature",
+          bin: { maxbins: 20 },
+          type: "quantitative",
+        },
+        y: { aggregate: "count", type: "quantitative" },
+      },
+    } as VegaLiteUnitSpec;
+    expect(getBinnedFields(spec)).toEqual(["temperature"]);
+  });
+
+  it("should ignore encodings without field property", () => {
+    const spec = {
+      mark: "bar",
+      encoding: {
+        x: { bin: true, type: "quantitative" },
+        y: { field: "y", type: "quantitative" },
+      },
+    } as VegaLiteUnitSpec;
+    expect(getBinnedFields(spec)).toEqual([]);
+  });
+});
+
+describe("ParamNames", () => {
+  describe("binColoring", () => {
+    it("should generate bin_coloring for undefined layer", () => {
+      expect(ParamNames.binColoring(undefined)).toBe("bin_coloring");
+    });
+
+    it("should generate bin_coloring_0 for layer 0", () => {
+      expect(ParamNames.binColoring(0)).toBe("bin_coloring_0");
+    });
+
+    it("should generate bin_coloring_1 for layer 1", () => {
+      expect(ParamNames.binColoring(1)).toBe("bin_coloring_1");
+    });
+  });
+
+  describe("isBinColoring", () => {
+    it("should return true for bin_coloring", () => {
+      expect(ParamNames.isBinColoring("bin_coloring")).toBe(true);
+    });
+
+    it("should return true for bin_coloring_0", () => {
+      expect(ParamNames.isBinColoring("bin_coloring_0")).toBe(true);
+    });
+
+    it("should return true for bin_coloring_123", () => {
+      expect(ParamNames.isBinColoring("bin_coloring_123")).toBe(true);
+    });
+
+    it("should return false for select_point", () => {
+      expect(ParamNames.isBinColoring("select_point")).toBe(false);
+    });
+
+    it("should return false for select_interval", () => {
+      expect(ParamNames.isBinColoring("select_interval")).toBe(false);
+    });
+
+    it("should return false for legend_selection_field", () => {
+      expect(ParamNames.isBinColoring("legend_selection_field")).toBe(false);
+    });
+  });
+});

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

@@ -1,5 +1,6 @@
 /* Copyright 2024 Marimo. All rights reserved. */
 import { Marks } from "./marks";
+import { ParamNames } from "./params";
 import type {
   AnyMark,
   Encodings,
@@ -45,7 +46,7 @@ export function findEncodedFields(spec: VegaLiteSpec): string[] {
     if (!encoding) {
       return [];
     }
-    if (!ALLOWED_ENCODING_TYPES.has(key as EncodingType)) {
+    if (!ALLOWED_ENCODING_TYPES.has(key)) {
       return [];
     }
 
@@ -84,8 +85,21 @@ export function makeEncodingInteractive(
   paramNames: string[],
   mark: AnyMark | undefined,
 ): SharedCompositeEncoding<Field> {
+  // For binned charts, we only use the bin_coloring param for opacity.
+  // The regular selection params (point/interval) are used for backend filtering only.
+  // This separation allows us to control which params trigger visual feedback vs data filtering.
+  // NOTE: Bin + interval selection does not change the opacity at all.
+  const opacityParams = paramNames.filter((paramName) =>
+    ParamNames.isBinColoring(paramName),
+  );
+
+  // If we have bin_coloring params, use only those for opacity.
+  // Otherwise, use all params (non-binned chart behavior).
+  const relevantParams = opacityParams.length > 0 ? opacityParams : paramNames;
+
+  // Use AND so all conditions must be met
   const test = {
-    and: paramNames.map((paramName) => ({
+    and: relevantParams.map((paramName) => ({
       param: paramName,
     })),
   };

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

@@ -1,16 +1,283 @@
 /* Copyright 2024 Marimo. All rights reserved. */
 
+import type { TopLevelSpec } from "vega-lite";
+import type { NonNormalizedSpec } from "vega-lite/types_unstable/spec/index.js";
+import type { TopLevelParameter } from "vega-lite/types_unstable/spec/toplevel.js";
+
 import { findEncodedFields, makeEncodingInteractive } from "./encodings";
 import { Marks } from "./marks";
-import { Params } from "./params";
+import { getBinnedFields, Params } from "./params";
 import type {
+  Field,
   GenericVegaSpec,
+  LayerSpec,
   Mark,
+  SelectionParameter,
   SelectionType,
+  UnitSpec,
   VegaLiteSpec,
   VegaLiteUnitSpec,
 } from "./types";
 
+/**
+ * Creates a unique signature for a param based on its select properties.
+ * Params with the same signature are considered "common" candidates for hoisting.
+ */
+function getParamSignature(param: TParams): string {
+  // For non-selection params, use the whole param as signature
+  if (!("select" in param) || !param.select) {
+    return JSON.stringify(param);
+  }
+
+  const select = param.select;
+
+  // Handle string selections (type shortcuts)
+  if (typeof select === "string") {
+    return JSON.stringify({ type: select, bind: param.bind });
+  }
+
+  const signature = {
+    type: select.type,
+    encodings:
+      "encodings" in select && select.encodings
+        ? [...select.encodings].sort()
+        : undefined,
+    fields:
+      "fields" in select && select.fields
+        ? [...select.fields].sort()
+        : undefined,
+    bind: param.bind,
+  };
+
+  return JSON.stringify(signature);
+}
+
+/**
+ * Recursively collects all params from nested specs and hoists ONLY common params to the top level.
+ * Common params are those with the same select.type, select.encodings, select.fields, and bind
+ * that appear in ALL unit specs.
+ */
+function hoistParamsAndApplyOpacity<T extends VegaLiteSpec>(spec: T): T {
+  // Collect params from all unit specs
+  const allUnitSpecParams = collectAllUnitSpecParams(spec);
+
+  if (allUnitSpecParams.length === 0) {
+    return spec;
+  }
+
+  // Find common params (params with same signature that appear in all unit specs)
+  const commonParams = findCommonParams(allUnitSpecParams);
+
+  if (commonParams.length === 0) {
+    return spec;
+  }
+
+  // Remove only common params from nested specs
+  const commonParamNames = new Set(commonParams.map((p) => p.name));
+  const specWithoutCommonParams = removeSpecificParamsFromNestedSpecs(
+    spec,
+    commonParamNames,
+  );
+
+  // Apply opacity to all nested unit specs based on hoisted params
+  const specWithOpacity = applyOpacityToNestedSpecs(
+    specWithoutCommonParams,
+    commonParams.map((p) => p.name),
+  );
+
+  // Add common params to top level
+  return {
+    ...specWithOpacity,
+    params: [...(spec.params || []), ...commonParams],
+  } as T;
+}
+
+type SpecWithParams =
+  | TopLevelSpec
+  | LayerSpec<Field>
+  | UnitSpec<Field>
+  | NonNormalizedSpec;
+
+type TParams = SelectionParameter | TopLevelParameter;
+
+/**
+ * Collects params from all unit specs (not concat specs).
+ * Returns array of { params } for each unit spec.
+ */
+function collectAllUnitSpecParams(spec: SpecWithParams): {
+  params: TParams[];
+}[] {
+  const results: { params: TParams[] }[] = [];
+
+  if ("vconcat" in spec && Array.isArray(spec.vconcat)) {
+    for (const subSpec of spec.vconcat) {
+      results.push(...collectAllUnitSpecParams(subSpec));
+    }
+  } else if ("hconcat" in spec && Array.isArray(spec.hconcat)) {
+    for (const subSpec of spec.hconcat) {
+      results.push(...collectAllUnitSpecParams(subSpec));
+    }
+  } else if ("layer" in spec) {
+    // Don't collect from layers, as they handle their own params
+    return [];
+  } else if (
+    "mark" in spec && // This is a unit spec
+    "params" in spec &&
+    spec.params &&
+    spec.params.length > 0
+  ) {
+    results.push({ params: spec.params });
+  }
+
+  return results;
+}
+
+/**
+ * Finds params that are common across all unit specs.
+ * A param is common if it has the same signature and appears in all unit specs.
+ */
+function findCommonParams(
+  allUnitSpecParams: { params: TParams[] }[],
+): TParams[] {
+  if (allUnitSpecParams.length === 0) {
+    return [];
+  }
+
+  // Count occurrences of each param signature
+  const signatureCounts = new Map<string, { count: number; param: TParams }>();
+  const totalUnitSpecs = allUnitSpecParams.length;
+
+  for (const { params } of allUnitSpecParams) {
+    const seenSignatures = new Set<string>();
+
+    for (const param of params) {
+      const signature = getParamSignature(param);
+
+      // Only count once per unit spec (avoid duplicates within same spec)
+      if (!seenSignatures.has(signature)) {
+        seenSignatures.add(signature);
+
+        if (!signatureCounts.has(signature)) {
+          signatureCounts.set(signature, { count: 0, param });
+        }
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        signatureCounts.get(signature)!.count++;
+      }
+    }
+  }
+
+  // Return params that appear in ALL unit specs
+  const commonParams: TParams[] = [];
+  for (const [, { count, param }] of signatureCounts) {
+    if (count === totalUnitSpecs) {
+      commonParams.push(param);
+    }
+  }
+
+  return commonParams;
+}
+
+/**
+ * Recursively removes specific params (by name) from nested specs.
+ */
+function removeSpecificParamsFromNestedSpecs(
+  spec: SpecWithParams,
+  paramNamesToRemove: Set<string>,
+): SpecWithParams {
+  if ("vconcat" in spec && Array.isArray(spec.vconcat)) {
+    return {
+      ...spec,
+      vconcat: spec.vconcat.map((subSpec) =>
+        removeSpecificParamsFromNestedSpecs(subSpec, paramNamesToRemove),
+      ),
+    } as SpecWithParams;
+  }
+
+  if ("hconcat" in spec && Array.isArray(spec.hconcat)) {
+    return {
+      ...spec,
+      hconcat: spec.hconcat.map((subSpec) =>
+        removeSpecificParamsFromNestedSpecs(subSpec, paramNamesToRemove),
+      ),
+    } as SpecWithParams;
+  }
+
+  if ("mark" in spec && "params" in spec && spec.params) {
+    // This is a unit spec, filter out params that should be hoisted
+    const currentParams = spec.params;
+    const filteredParams: TParams[] = [];
+
+    for (const param of currentParams) {
+      if (!param || typeof param !== "object" || !("name" in param)) {
+        filteredParams.push(param);
+        continue;
+      }
+      if (!paramNamesToRemove.has(param.name)) {
+        filteredParams.push(param);
+      }
+    }
+
+    if (filteredParams.length === 0) {
+      const { params, ...rest } = spec;
+      return rest as SpecWithParams;
+    }
+
+    return {
+      ...spec,
+      params: filteredParams,
+    } as SpecWithParams;
+  }
+
+  return spec;
+}
+
+/**
+ * Recursively applies opacity encoding to all unit specs based on param names.
+ */
+function applyOpacityToNestedSpecs<T extends SpecWithParams>(
+  spec: T,
+  paramNames: string[],
+): T {
+  if ("vconcat" in spec && Array.isArray(spec.vconcat)) {
+    return {
+      ...spec,
+      vconcat: spec.vconcat.map((subSpec) =>
+        applyOpacityToNestedSpecs(subSpec, paramNames),
+      ),
+    };
+  }
+
+  if ("hconcat" in spec && Array.isArray(spec.hconcat)) {
+    return {
+      ...spec,
+      hconcat: spec.hconcat.map((subSpec) =>
+        applyOpacityToNestedSpecs(subSpec, paramNames),
+      ),
+    };
+  }
+
+  if ("layer" in spec) {
+    // Don't apply to layers, they handle their own opacity
+    return spec;
+  }
+
+  if ("mark" in spec && Marks.isInteractive(spec.mark)) {
+    // This is a unit spec, apply opacity
+    return {
+      ...spec,
+      mark: Marks.makeClickable(spec.mark),
+      encoding: makeEncodingInteractive(
+        "opacity",
+        spec.encoding || {},
+        paramNames,
+        spec.mark,
+      ),
+    };
+  }
+
+  return spec;
+}
+
 export function makeSelectable<T extends VegaLiteSpec>(
   spec: T,
   opts: {
@@ -38,26 +305,71 @@ export function makeSelectable<T extends VegaLiteSpec>(
 
   if ("vconcat" in spec) {
     const subSpecs = spec.vconcat.map((subSpec) =>
-      "mark" in subSpec ? makeChartInteractive(subSpec) : subSpec,
+      "mark" in subSpec
+        ? makeSelectable(subSpec as VegaLiteUnitSpec, {
+            chartSelection,
+            fieldSelection,
+          })
+        : subSpec,
     );
-    // No pan/zoom for vconcat
-    return { ...spec, vconcat: subSpecs };
+    // Hoist params to top level and apply opacity to all nested specs
+    return hoistParamsAndApplyOpacity({ ...spec, vconcat: subSpecs });
   }
 
   if ("hconcat" in spec) {
     const subSpecs = spec.hconcat.map((subSpec) =>
-      "mark" in subSpec ? makeChartInteractive(subSpec) : subSpec,
+      "mark" in subSpec
+        ? makeSelectable(subSpec as VegaLiteUnitSpec, {
+            chartSelection,
+            fieldSelection,
+          })
+        : subSpec,
     );
-    // No pan/zoom for hconcat
-    return { ...spec, hconcat: subSpecs };
+    // Hoist params to top level and apply opacity to all nested specs
+    return hoistParamsAndApplyOpacity({ ...spec, hconcat: subSpecs });
   }
 
   if ("layer" in spec) {
+    // Check if has top-level params already (not just legend). If so, we don't add any more as it
+    // will cause conflicts.
+    const hasTopLevelParams = spec.params && spec.params.length > 0;
+    const shouldAddLegendSelection =
+      fieldSelection !== false && !hasTopLevelParams;
+
+    // Collect all unique legend fields from all layers to avoid duplicates
+    let legendFields: string[] = [];
+    if (shouldAddLegendSelection) {
+      const allFields = spec.layer.flatMap((subSpec) => {
+        if (!("mark" in subSpec)) {
+          return [];
+        }
+        return findEncodedFields(subSpec as VegaLiteUnitSpec);
+      });
+      legendFields = [...new Set(allFields)]; // Remove duplicates
+
+      // If fieldSelection is an array, filter the fields
+      if (Array.isArray(fieldSelection)) {
+        legendFields = legendFields.filter((field) =>
+          fieldSelection.includes(field),
+        );
+      }
+    }
+
     const subSpecs = spec.layer.map((subSpec, idx) => {
       if (!("mark" in subSpec)) {
         return subSpec;
       }
       let resolvedSpec = subSpec as VegaLiteUnitSpec;
+
+      // Only add legend params to first
+      if (idx === 0 && legendFields.length > 0) {
+        const legendParams = legendFields.map((field) => Params.legend(field));
+        resolvedSpec = {
+          ...resolvedSpec,
+          params: [...(resolvedSpec.params || []), ...legendParams],
+        };
+      }
+
       resolvedSpec = makeChartSelectable(resolvedSpec, chartSelection, idx);
       resolvedSpec = makeChartInteractive(resolvedSpec);
       if (idx === 0) {
@@ -147,10 +459,19 @@ function makeChartSelectable(
     return spec;
   }
 
-  const resolvedChartSelection =
-    chartSelection === true ? getBestSelectionForMark(mark) : [chartSelection];
+  const binnedFields = getBinnedFields(spec);
+
+  // If chartSelection is true, we use the best selection for based on the spec
+  // For binned charts, we use point selection
+  // Otherwise, we use the best selection for the mark
+  const resolvedChartSelection: SelectionType[] | undefined =
+    chartSelection === true
+      ? binnedFields.length > 0
+        ? ["point"]
+        : getBestSelectionForMark(mark)
+      : [chartSelection];
 
-  if (!resolvedChartSelection) {
+  if (!resolvedChartSelection || resolvedChartSelection.length === 0) {
     return spec;
   }
 
@@ -162,6 +483,14 @@ function makeChartSelectable(
 
   const nextParams = [...(spec.params || []), ...params];
 
+  // For binned charts, we need TWO params:
+  // 1. The regular selection param (point/interval) - sends signals to backend for filtering
+  // 2. The bin_coloring param - controls opacity/coloring, NO signal listener
+  // This separation allows us to filter on binned ranges while providing visual feedback
+  if (binnedFields.length > 0 && resolvedChartSelection.includes("point")) {
+    nextParams.push(Params.binColoring(layerNum));
+  }
+
   return {
     ...spec,
     params: nextParams,

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

@@ -1,12 +1,16 @@
 /* Copyright 2024 Marimo. All rights reserved. */
+
+import { uniq } from "lodash-es";
 import type { TopLevelSpec } from "vega-lite";
-import type { LayerSpec, UnitSpec } from "vega-lite/build/src/spec";
+import type { NonNormalizedSpec } from "vega-lite/types_unstable/spec/index.js";
 import { Marks } from "./marks";
 import {
   type Field,
+  type LayerSpec,
   Mark,
   type SelectionParameter,
   type SingleDefUnitChannel,
+  type UnitSpec,
   type VegaLiteUnitSpec,
 } from "./types";
 
@@ -20,6 +24,14 @@ export const ParamNames = {
   legendSelection(field: string) {
     return `legend_selection_${field}`;
   },
+  /**
+   * Special param for binned charts that controls opacity/coloring.
+   * This param is used for visual feedback only and does NOT send signals to the backend.
+   * The actual selection param (point/interval) handles backend filtering.
+   */
+  binColoring(layerNum: number | undefined) {
+    return layerNum == null ? "bin_coloring" : `bin_coloring_${layerNum}`;
+  },
   HIGHLIGHT: "highlight",
   PAN_ZOOM: "pan_zoom",
   hasPoint(names: string[]) {
@@ -34,6 +46,9 @@ export const ParamNames = {
   hasPanZoom(names: string[]) {
     return names.some((name) => name.startsWith("pan_zoom"));
   },
+  isBinColoring(name: string) {
+    return name.startsWith("bin_coloring");
+  },
 };
 
 export const Params = {
@@ -78,6 +93,20 @@ export const Params = {
       },
     };
   },
+  /**
+   * Creates a param for binned charts that controls opacity/coloring only.
+   * This param does NOT send signals to the backend - it's purely for visual feedback.
+   * The regular selection param (point/interval) handles backend filtering.
+   */
+  binColoring(layerNum: number | undefined): SelectionParameter<"point"> {
+    return {
+      name: ParamNames.binColoring(layerNum),
+      select: {
+        type: "point",
+        on: "click[!event.metaKey]",
+      },
+    };
+  },
   legend(field: string): SelectionParameter<"point"> {
     return {
       name: ParamNames.legendSelection(field),
@@ -136,25 +165,30 @@ export function getEncodingAxisForMark(
 }
 
 export function getSelectionParamNames(
-  spec: TopLevelSpec | LayerSpec<Field> | UnitSpec<Field>,
+  spec: TopLevelSpec | LayerSpec<Field> | UnitSpec<Field> | NonNormalizedSpec,
 ): string[] {
   if ("params" in spec && spec.params && spec.params.length > 0) {
     const params = spec.params;
-    return (
-      params
+    const paramNames = 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
-        .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)
-    );
+        return "select" in param && param.select !== undefined;
+      })
+      .map((param) => param.name);
+    return uniq(paramNames);
   }
   if ("layer" in spec) {
-    return [...new Set(spec.layer.flatMap(getSelectionParamNames))];
+    return uniq(spec.layer.flatMap(getSelectionParamNames));
+  }
+  if ("vconcat" in spec) {
+    return uniq(spec.vconcat.flatMap(getSelectionParamNames));
+  }
+  if ("hconcat" in spec) {
+    return uniq(spec.hconcat.flatMap(getSelectionParamNames));
   }
   return [];
 }
@@ -190,3 +224,31 @@ export function getDirectionOfBar(
 
   return undefined;
 }
+
+/**
+ * Returns the binned field names from the spec.
+ * For binned charts, selections need to use fields instead of encodings.
+ */
+export function getBinnedFields(spec: VegaLiteUnitSpec): string[] {
+  if (!spec.encoding) {
+    return [];
+  }
+
+  const fields: string[] = [];
+
+  for (const channel of Object.values(spec.encoding)) {
+    // Check for binning
+    if (
+      channel &&
+      typeof channel === "object" &&
+      "bin" in channel &&
+      channel.bin &&
+      "field" in channel &&
+      typeof channel.field === "string"
+    ) {
+      fields.push(channel.field);
+    }
+  }
+
+  return fields;
+}