Merge branch 'main' into yogesh-xxx-fix-vega-warnings

Author: b-yogesh

chartlets.js/CHANGES.md

@@ -1,3 +1,11 @@
+## Version 0.0.23 (in development)
+
+* Replacing entire components if a related component `StateChange` 
+  has an empty `property`. (#38)
+
+* Added handy hooks `useContributions` and `useComponentChangeHandlers`.
+
+
 ## Version 0.0.22 (from 2024/11/19)
 
 * Improved robustness while rendering the in `Select` component

chartlets.js/src/demo/components/PanelsRow.tsx

@@ -1,20 +1,18 @@
-import { type ComponentChangeEvent, handleComponentChange } from "@/lib";
-import { usePanelStates } from "@/demo/hooks";
+import type { PanelState } from "@/demo/types";
+import { useComponentChangeHandlers, useContributions } from "@/lib/hooks";
 import Panel from "./Panel";
 
 function PanelsRow() {
-  const panelStates = usePanelStates();
+  const panelStates = useContributions<PanelState>("panels");
+  const panelChangeHandlers = useComponentChangeHandlers(
+    "panels",
+    panelStates?.length || 0,
+  );
   if (!panelStates) {
     // Ok, not ready yet
     return null;
   }
 
-  const handlePanelChange = (
-    panelIndex: number,
-    panelEvent: ComponentChangeEvent,
-  ) => {
-    handleComponentChange("panels", panelIndex, panelEvent);
-  };
   const panels = panelStates.map((panelState, panelIndex) => {
     const { container, component, componentResult } = panelState;
     return (
@@ -24,7 +22,7 @@ function PanelsRow() {
         componentProps={component}
         componentStatus={componentResult.status}
         componentError={componentResult.error}
-        onChange={(e) => handlePanelChange(panelIndex, e)}
+        onChange={panelChangeHandlers[panelIndex]}
       />
     );
   });

chartlets.js/src/demo/hooks.ts

@@ -3,6 +3,7 @@ import { describe, it, expect } from "vitest";
 import { type ContribPoint } from "@/lib/types/model/extension";
 import { type StateChangeRequest } from "@/lib/types/model/callback";
 import {
+  type BoxState,
   type ComponentState,
   type PlotState,
 } from "@/lib/types/state/component";
@@ -112,4 +113,24 @@ describe("Test that applyComponentStateChange()", () => {
     });
     expect(newState).toBe(componentTree);
   });
+
+  it("replaces state if property is empty string", () => {
+    const value: BoxState = {
+      type: "Box",
+      id: "b1",
+      children: ["Hello", "World"],
+    };
+    const newState = applyComponentStateChange(componentTree, {
+      link: "component",
+      id: "b1",
+      property: "",
+      value,
+    });
+    expect(newState).toBe(value);
+    expect(newState).toEqual({
+      type: "Box",
+      id: "b1",
+      children: ["Hello", "World"],
+    });
+  });
 });

chartlets.js/src/lib/actions/helpers/applyStateChangeRequests.test.ts

@@ -30,39 +30,6 @@ export function applyStateChangeRequests(
   applyHostStateChanges(stateChangeRequests);
 }
 
-function applyHostStateChanges(stateChangeRequests: StateChangeRequest[]) {
-  const { configuration } = store.getState();
-  const { hostStore } = configuration;
-  if (hostStore) {
-    const hostStateOld = hostStore.getState();
-    let hostState: object | undefined = hostStateOld;
-    stateChangeRequests.forEach((stateChangeRequest) => {
-      hostState = applyStateChanges(
-        hostState,
-        stateChangeRequest.stateChanges.filter(
-          (stateChange) => stateChange.link === "app",
-        ),
-      );
-    });
-    if (hostState !== hostStateOld) {
-      hostStore.setState(hostState);
-    }
-  }
-}
-
-function applyComponentStateChanges(
-  componentOld: ComponentState | undefined,
-  stateChanges: StateChange[],
-) {
-  let component = componentOld;
-  if (component) {
-    stateChanges.forEach((stateChange) => {
-      component = applyComponentStateChange(component!, stateChange);
-    });
-  }
-  return component;
-}
-
 // we export for testing only
 export function applyContributionChangeRequests(
   contributionsRecord: Record<ContribPoint, ContributionState[]>,
@@ -101,22 +68,40 @@ export function applyContributionChangeRequests(
   return contributionsRecord;
 }
 
+function applyComponentStateChanges(
+  componentOld: ComponentState | undefined,
+  stateChanges: StateChange[],
+) {
+  let component = componentOld;
+  if (component) {
+    stateChanges.forEach((stateChange) => {
+      component = applyComponentStateChange(component!, stateChange);
+    });
+  }
+  return component;
+}
+
 // we export for testing only
 export function applyComponentStateChange(
   component: ComponentState,
   stateChange: StateChange,
 ): ComponentState {
-  if (component.id === stateChange.id) {
+  if (isComponentState(component) && component.id === stateChange.id) {
     const property = normalizeObjPath(stateChange.property);
-    const valueOld = getValue(component, property);
     const valueNew = stateChange.value;
+    if (property.length === 0) {
+      // Special case: If no property given, replace entire component.
+      // But only if it is one, otherwise don't change state.
+      return isComponentState(valueNew) ? valueNew : component;
+    }
+    const valueOld = getValue(component, property);
     if (
       property[property.length - 1] === "children" &&
       !Array.isArray(valueNew) &&
       valueNew !== null &&
       valueNew !== undefined
     ) {
-      // Special case if the value of "children" is changed:
+      // Special case: if the value of "children" is changed:
       // convert scalar valueNew into one-element array
       return setValue(component, property, [valueNew]);
     } else if (valueOld !== valueNew) {
@@ -145,6 +130,26 @@ export function applyComponentStateChange(
   return component;
 }
 
+function applyHostStateChanges(stateChangeRequests: StateChangeRequest[]) {
+  const { configuration } = store.getState();
+  const { hostStore } = configuration;
+  if (hostStore) {
+    const hostStateOld = hostStore.getState();
+    let hostState: object | undefined = hostStateOld;
+    stateChangeRequests.forEach((stateChangeRequest) => {
+      hostState = applyStateChanges(
+        hostState,
+        stateChangeRequest.stateChanges.filter(
+          (stateChange) => stateChange.link === "app",
+        ),
+      );
+    });
+    if (hostState !== hostStateOld) {
+      hostStore.setState(hostState);
+    }
+  }
+}
+
 // we export for testing only
 export function applyStateChanges<S extends object | undefined>(
   state: S,

chartlets.js/src/lib/actions/helpers/applyStateChangeRequests.ts

@@ -2,13 +2,17 @@ import type { StoreState } from "@/lib/types/state/store";
 import { store } from "@/lib/store";
 import { useCallback, useMemo } from "react";
 import type { ContributionState } from "@/lib/types/state/contribution";
-import type { ComponentChangeHandler } from "@/lib/types/state/event";
 import {
   isTopLevelSelectionParameter,
   type SignalHandler,
 } from "@/lib/types/state/vega";
 import type { TopLevelSpec } from "vega-lite/src/spec";
 import { isString } from "@/lib/utils/isString";
+import type {
+  ComponentChangeEvent,
+  ComponentChangeHandler,
+} from "@/lib/types/state/event";
+import { handleComponentChange } from "@/lib/actions/handleComponentChange";
 
 const selectConfiguration = (state: StoreState) => state.configuration;
 
@@ -135,5 +139,44 @@ export function useSignalListeners(
   return useMemo(
     () => createSignalListeners(signals),
     [createSignalListeners, signals],
+
+/**
+ * A hook that retrieves the contributions for the given contribution
+ * point given by `contribPoint`.
+ *
+ * @param contribPoint Contribution point name.
+ * @typeParam S Type of the container state.
+ */
+export function useContributions<S extends object = object>(
+  contribPoint: string,
+): ContributionState<S>[] {
+  const contributionsRecord = useContributionsRecord();
+  return contributionsRecord[contribPoint] as ContributionState<S>[];
+}
+
+/**
+ * A hook that creates an array of length `numContribs` with stable
+ * component change handlers of type `ComponentChangeHandler` for
+ * the contribution point given by `contribPoint`.
+ *
+ * @param contribPoint Contribution point name.
+ * @param numContribs Number of contributions. This should be the length
+ *   of the array of contributions you get using the `useContributions` hook.
+ */
+export function useComponentChangeHandlers(
+  contribPoint: string,
+  numContribs: number,
+): ComponentChangeHandler[] {
+  return useMemo(
+    () =>
+      Array.from({ length: numContribs }).map(
+        (_, contribIndex) => (componentEvent: ComponentChangeEvent) =>
+          void handleComponentChange(
+            contribPoint,
+            contribIndex,
+            componentEvent,
+          ),
+      ),
+    [contribPoint, numContribs],
   );
 }

chartlets.js/src/lib/hooks.ts

@@ -18,5 +18,7 @@ export {
   useExtensions,
   useContributionsResult,
   useContributionsRecord,
+  useContributions,
+  useComponentChangeHandlers,
   makeContributionsHook,
 } from "@/lib/hooks";

chartlets.js/src/lib/index.ts

@@ -1,5 +1,8 @@
 ## Version 0.0.22 (in development)
 
+* Replacing components is now possible by using an 
+  `Output` with `property` set to an empty string. (#38)
+
 * `Component` children can now also be text nodes (of type `string`).
 
 * `Typography` component has children instead of `text`.

chartlets.py/CHANGES.md

@@ -1,13 +1,21 @@
 from abc import ABC
 from typing import Any, Literal
 
-from .util.assertions import assert_is_instance_of
-from .util.assertions import assert_is_none
-from .util.assertions import assert_is_one_of
+from .util.assertions import (
+    assert_is_given,
+    assert_is_instance_of,
+    assert_is_none,
+    assert_is_one_of,
+)
 
 
 Link = Literal["component"] | Literal["container"] | Literal["app"]
 
+COMPONENT = ""
+"""Special property value that can be used 
+to refer to the entire component.
+"""
+
 
 class Channel(ABC):
     """Base class for `Input`, `State`, and `Output`.
@@ -53,7 +61,8 @@ class Input(Channel):
     Args:
         id:
             Value of a component's "id" property.
-            Used only if `source` is `"component"`.
+            Required, if `source` is `"component"` (the default).
+            Otherwise, it must not be passed.
         property:
             Name of the property of a component or state.
             To address properties in nested objects or arrays
@@ -82,7 +91,7 @@ class State(Input):
 
     Just like an `Input`, a `State` describes from which property in which state
     a parameter value is read, but according state changes
-    will **not*Ü* trigger callback invocation.
+    will **not* trigger callback invocation.
 
     Args:
         id:
@@ -125,6 +134,8 @@ class Output(Channel):
             To address properties in nested objects or arrays
             use a dot (`.`) to separate property names and array
             indexes.
+            If `target` is `"component"` the empty string can be used
+            to refer to entire components.
         target: One of `"component"` (the default), `"container"`,
             or `"app"`.
     """
@@ -154,22 +165,37 @@ def _validate_input_params(
 def _validate_output_params(
     target: Link | None, id: str | None, property: str | None
 ) -> tuple[Link, str | None, str | None]:
-    return _validate_params("target", target, id, property)
+    return _validate_params("target", target, id, property, output=True)
 
 
 # noinspection PyShadowingBuiltins
 def _validate_params(
-    link_name: str, link: Link | None, id: str | None, property: str | None
+    link_name: str,
+    link: Link | None,
+    id: str | None,
+    property: str | None,
+    output: bool = False,
 ) -> tuple[Link, str | None, str | None]:
-    assert_is_one_of(link_name, link, ("component", "container", "app", None))
-    if not link or link == "component":
-        assert_is_instance_of("id", id, (str, NoneType))
+    if link is None or link == "component":
+        # Component states require an id
+        # and property which defaults to "value"
+        link = "component"
+        assert_is_given("id", id)
+        assert_is_instance_of("id", id, str)
         assert_is_instance_of("property", id, (str, NoneType))
-        link = link or "component"
-        if property is None and id is not None:
+        if property is None:
+            # property, if not provided, defaults to "value"
             property = "value"
+        elif not output:
+            # outputs are allowed to have an empty property value
+            assert_is_given("property", property)
     else:
-        assert_is_none("id", id)
+        # Other states require a link and property
+        # and should have no id
+        assert_is_given(link_name, link)
+        assert_is_one_of(link_name, link, ("container", "app"))
+        assert_is_given("property", property)
         assert_is_instance_of("property", property, str)
+        assert_is_none("id", id)
     # noinspection PyTypeChecker
     return link, id, property

chartlets.py/chartlets/channel.py

@@ -18,3 +18,8 @@ def assert_is_instance_of(name: str, value: Any, type_set: Type | tuple[Type, ..
 def assert_is_none(name: str, value: Any):
     if value is not None:
         raise TypeError(f"value of {name!r} must be None, but was {value!r}")
+
+
+def assert_is_given(name: str, value: Any):
+    if not value:
+        raise ValueError(f"value for {name!r} must be given")