Added comments

Author: b-yogesh

chartlets.js/src/lib/components/Plot.tsx

@@ -6,28 +6,47 @@ import type { TopLevelParameter } from "vega-lite/src/spec/toplevel";
 import type { TopLevelSelectionParameter } from "vega-lite/src/selection";
 import type { Stream } from "vega-typings/types/spec/stream";
 
+type SignalHandler = (signalName: string, value: unknown) => void;
+
 export interface PlotProps extends Omit<PlotState, "type"> {
   onChange: ComponentChangeHandler;
 }
 
+/*
+There are two types of Parameters in Vega-lite. Variable and Selection parameters. We need to check if the provided
+parameter in the chart from the server is a Selection parameter so that we can extract the selection event types
+(point or interval) and further, the events from the `select.on` property (e.g. click, mouseover, keydown etc.) if
+that property `on` exists. We need these events and their names to create the signal listeners and pass them to the
+Vega-lite element for event-handling (signal-listeners).
+*/
+function isTopLevelSelectionParameter(
+  param: TopLevelParameter,
+): param is TopLevelSelectionParameter {
+  return "select" in param;
+}
+
+/*
+The signal name extracted from the `select.on` property can be either a string or of Stream type (internal Vega
+type). But since we create the selection events in Altair (in the server) using `on="click"` etc., the event type
+will be a string, but we need this type-guard to be sure. If it is a Stream object, that case is not handled yet.
+*/
+function isString(signal_name: string | Stream): signal_name is string {
+  return typeof signal_name === "string";
+}
+
 export function Plot({ id, style, chart, onChange }: PlotProps) {
   if (!chart) {
     return <div id={id} style={style} />;
   }
 
-  function isTopLevelSelectionParameter(
-    param: TopLevelParameter,
-  ): param is TopLevelSelectionParameter {
-    return "select" in param;
-  }
-
-  function isString(signal_name: string | Stream): signal_name is string {
-    return typeof signal_name === "string";
-  }
-
   const signals: { [key: string]: string } = {};
 
+  /*
+  Here, we loop through all the params to create map of signals which will be then used to create the map of
+  signal-listeners
+  */
   chart.params?.forEach((param) => {
+    console.log("param", param);
     if (isTopLevelSelectionParameter(param)) {
       if (
         typeof param.select === "object" &&
@@ -37,6 +56,12 @@ export function Plot({ id, style, chart, onChange }: PlotProps) {
         const signal_name = param.select.on;
         if (isString(signal_name)) {
           signals[signal_name] = param.name;
+        } else {
+          console.warn(
+            "The signal " +
+              param +
+              " is of Stream type (internal Vega-lite type) which is not handled yet.",
+          );
         }
       }
     }
@@ -55,13 +80,16 @@ export function Plot({ id, style, chart, onChange }: PlotProps) {
     }
   };
 
-  type SignalHandler = (signalName: string, value: unknown) => void;
-
-  // Currently, we only have click events support, but if more are required, they can be implemented and added in the map below.
+  /*
+  Currently, we only have click events support, but if more are required, they can be implemented and added in the map below.
+   */
   const signalHandlerMap: { [key: string]: SignalHandler } = {
     click: handleClickSignal,
   };
 
+  /*
+  This function creates the map of signal listeners based on the `signals` map computed above.
+  */
   const createSignalListeners = (signals: { [key: string]: string }) => {
     const signalListeners: { [key: string]: SignalHandler } = {};
     Object.entries(signals).forEach(([event, signalName]) => {

chartlets.js/src/lib/types/state/component.ts

@@ -1,6 +1,6 @@
 import { type CSSProperties } from "react";
 import { isObject } from "@/lib/utils/isObject";
-import type {TopLevelSpec} from "vega-lite/src/spec";
+import type { TopLevelSpec } from "vega-lite/src/spec";
 
 export type ComponentType =
   | "Box"
@@ -54,7 +54,7 @@ export interface CheckboxState extends ComponentState {
 export interface PlotState extends ComponentState {
   type: "Plot";
   chart:
-    | TopLevelSpec
+    | TopLevelSpec // This is the vega-lite specification type
     | null;
 }