Merge pull request #39 from bcdev/forman-38-replace_components

Allow replacing components

Author: forman

chartlets.js/CHANGES.md

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

chartlets.js/src/lib/actions/helpers/applyStateChangeRequests.test.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.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.py/CHANGES.md

@@ -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/chartlets/channel.py

@@ -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/util/assertions.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")

chartlets.py/tests/channel_test.py

@@ -11,54 +11,48 @@ class ChannelTest(unittest.TestCase):
         channel_cls: Type[Channel]
         link_name: str
 
-        def test_no_args(self):
-            obj = self.channel_cls()
-            self.assertEqual("component", obj.link)
-            self.assertEqual(None, obj.id)
-            self.assertEqual(None, obj.property)
+        def test_no_args_given(self):
+            with pytest.raises(ValueError, match="value for 'id' must be given"):
+                obj = self.channel_cls()
 
         def test_id_given(self):
             obj = self.channel_cls("dataset_select")
             self.assertEqual("component", obj.link)
             self.assertEqual("dataset_select", obj.id)
             self.assertEqual("value", obj.property)
 
-        def test_app(self):
+        def test_app_ok(self):
             obj = self.channel_cls(property="datasetId", **{self.link_name: "app"})
             self.assertEqual("app", obj.link)
             self.assertEqual(None, obj.id)
             self.assertEqual("datasetId", obj.property)
 
         def test_container_with_id(self):
             with pytest.raises(
-                TypeError,
-                match="value of 'id' must be None, but was 'test_id'",
+                ValueError,
+                match="value for 'property' must be given",
             ):
                 self.channel_cls("test_id", **{self.link_name: "container"})
 
         def test_app_no_prop(self):
             with pytest.raises(
-                TypeError,
-                match=(
-                    "value of 'property' must be an instance"
-                    " of <class 'str'>, but was None"
-                ),
+                ValueError,
+                match="value for 'property' must be given",
             ):
                 self.channel_cls(**{self.link_name: "app"})
 
         def test_wrong_link(self):
             with pytest.raises(
                 ValueError,
                 match=(
-                    f"value of '{self.link_name}' must be one of"
-                    f" \\('component', 'container', 'app', None\\),"
-                    f" but was 'host'"
+                    f"value of {self.link_name!r} must be one of"
+                    r" \('container', 'app'\), but was 'host'"
                 ),
             ):
                 self.channel_cls(**{self.link_name: "host"})
 
         def test_no_trigger(self):
-            obj = self.channel_cls()
+            obj = self.channel_cls("some_id")
             if isinstance(obj, State):
                 self.assertTrue(obj.no_trigger)
             else:
@@ -93,6 +87,10 @@ class InputTest(make_base(), unittest.TestCase):
     channel_cls = Input
     link_name = "source"
 
+    def test_disallow_empty_property(self):
+        with pytest.raises(ValueError, match="value for 'property' must be given"):
+            self.channel_cls("some_id", "")
+
 
 class StateTest(make_base(), unittest.TestCase):
     channel_cls = State
@@ -102,3 +100,9 @@ class StateTest(make_base(), unittest.TestCase):
 class OutputTest(make_base(), unittest.TestCase):
     channel_cls = Output
     link_name = "target"
+
+    def test_allow_empty_property(self):
+        obj = self.channel_cls("some_id", "")
+        self.assertEqual("component", obj.link)
+        self.assertEqual("some_id", obj.id)
+        self.assertEqual("", obj.property)