feat: add resolveDataById utility to Puck API

Author: FedericoBonel

apps/docs/pages/docs/api-reference/puck-api.mdx

@@ -17,17 +17,18 @@ import { Callout } from "nextra/components";
 
 ## Params
 
-| Param                                             | Example                                            | Type                                                           |
-| ------------------------------------------------- | -------------------------------------------------- | -------------------------------------------------------------- |
-| [`appState`](#appstate)                           | `{ data: {}, ui: {} }`                             | [AppState](/docs/api-reference/data-model/app-state)           |
-| [`dispatch`](#dispatchaction)                     | `(action: PuckAction) => void`                     | Function                                                       |
-| [`getItemBySelector`](#getitembyselectorselector) | `() => ({ type: "Heading", props: {} })`           | Function                                                       |
-| [`getItemById`](#getitembyidid)                   | `() => ({ type: "Heading", props: {} })`           | Function                                                       |
-| [`getSelectorForId`](#getselectorforidid)         | `() => ({ index: 0, zone: 'Flex-123:children'  })` | Function                                                       |
-| [`getPermissions`](#getpermissionsparams)         | `() => ({ delete: true  })`                        | Function                                                       |
-| [`history`](#history)                             | `{}`                                               | Object                                                         |
-| [`refreshPermissions`](#refreshpermissionsparams) | `() => void`                                       | Function                                                       |
-| [`selectedItem`](#selecteditem)                   | `{ type: "Heading", props: {id: "my-heading"} }`   | [ComponentData](/docs/api-reference/data-model/data#content-1) |
+| Param                                                     | Example                                            | Type                                                           |
+| --------------------------------------------------------- | -------------------------------------------------- | -------------------------------------------------------------- |
+| [`appState`](#appstate)                                   | `{ data: {}, ui: {} }`                             | [AppState](/docs/api-reference/data-model/app-state)           |
+| [`dispatch`](#dispatchaction)                             | `(action: PuckAction) => void`                     | Function                                                       |
+| [`getItemBySelector`](#getitembyselectorselector)         | `() => ({ type: "Heading", props: {} })`           | Function                                                       |
+| [`getItemById`](#getitembyidid)                           | `() => ({ type: "Heading", props: {} })`           | Function                                                       |
+| [`getSelectorForId`](#getselectorforidid)                 | `() => ({ index: 0, zone: 'Flex-123:children'  })` | Function                                                       |
+| [`getPermissions`](#getpermissionsparams)                 | `() => ({ delete: true  })`                        | Function                                                       |
+| [`history`](#history)                                     | `{}`                                               | Object                                                         |
+| [`refreshPermissions`](#refreshpermissionsparams)         | `() => void`                                       | Function                                                       |
+| [`resolveComponentDataById`](#resolvecomponentdatabyidid) | `() => void`                                       | Function                                                       |
+| [`selectedItem`](#selecteditem)                           | `{ type: "Heading", props: {id: "my-heading"} }`   | [ComponentData](/docs/api-reference/data-model/data#content-1) |
 
 ### `appState`
 
@@ -253,6 +254,14 @@ Specify `type` to refresh the permissions for all components of a given componen
 refreshPermissions({ type: "HeadingBlock" });
 ```
 
+### `resolveComponentDataById(id)`
+
+Force a component to [resolve its data](/docs/api-reference/configuration/component-config#resolvedatadata-params) by id.
+
+```tsx
+resolveComponentDataById("Heading-1234");
+```
+
 ### `selectedItem`
 
 The currently selected item, as defined by `appState.ui.itemSelector`.

packages/core/lib/data/__tests__/resolve-component-data-by-id.spec.tsx

@@ -0,0 +1,159 @@
+import { act, waitFor } from "@testing-library/react";
+import { createAppStore, defaultAppState } from "../../../store";
+import { Config } from "../../../types";
+import { cache } from "../../resolve-component-data";
+import { resolveDataById } from "../resolve-data-by-id";
+import { walkAppState } from "../walk-app-state";
+
+const appStore = createAppStore();
+
+const childResolveData = jest.fn(async (data, params) => {
+  if (params.trigger === "force") {
+    return {
+      ...data,
+      props: {
+        resolvedProp: "Forced",
+      },
+    };
+  }
+
+  return data;
+});
+
+const config: Config = {
+  components: {
+    Parent: {
+      fields: { items: { type: "slot" } },
+      render: () => <div />,
+    },
+    Child: {
+      fields: {},
+      resolveData: childResolveData,
+      render: () => <div />,
+    },
+  },
+};
+
+function resetStores() {
+  appStore.setState(
+    {
+      ...appStore.getInitialState(),
+      config,
+      state: walkAppState(
+        {
+          ...defaultAppState,
+          data: {
+            ...defaultAppState.data,
+            content: [
+              {
+                type: "Parent",
+                props: {
+                  id: "Parent-1",
+                  items: [
+                    {
+                      type: "Child",
+                      props: {
+                        id: "Child-1",
+                      },
+                    },
+                    {
+                      type: "Child",
+                      props: {
+                        id: "Child-2",
+                      },
+                    },
+                    {
+                      type: "Child",
+                      props: {
+                        id: "Child-3",
+                      },
+                    },
+                  ],
+                },
+              },
+              {
+                type: "Parent",
+                props: {
+                  id: "Parent-2",
+                  items: [],
+                },
+              },
+            ],
+          },
+        },
+        config
+      ),
+    },
+    true
+  );
+}
+
+describe("useResolveDataOnMoved", () => {
+  beforeEach(async () => {
+    resetStores();
+    jest.clearAllMocks();
+    cache.lastChange = {};
+  });
+
+  it("resolves when called", async () => {
+    // When: ---------------
+    await act(() => resolveDataById("Child-1", appStore.getState));
+
+    // Then: ---------------
+    expect(childResolveData).toHaveBeenCalledTimes(1);
+    const mockedReturn = await childResolveData.mock.results[0].value;
+    expect(mockedReturn.props.resolvedProp).toBe("Forced");
+  });
+
+  it("resolves even if data hasn't changed", async () => {
+    // TODO: Change this when we solve race conditions over caches, it should be 3
+    const resolveAndCommitDataCalls = 6;
+
+    // When: ---------------
+    await act(async () => {
+      // This executes resolveData twice because of race conditions in cache
+      appStore.getState().resolveAndCommitData();
+    });
+
+    // TODO: Change this when we solve race conditions over caches, we shouldn't need to wait
+    await waitFor(() => Object.keys(cache.lastChange).length > 1);
+
+    await act(() => resolveDataById("Child-1", appStore.getState));
+
+    // Then: ---------------
+    const expectedCalls = resolveAndCommitDataCalls + 1;
+    expect(childResolveData).toHaveBeenCalledTimes(expectedCalls);
+    const mockedReturn = await childResolveData.mock.results[expectedCalls - 1]
+      .value;
+    expect(mockedReturn.props.resolvedProp).toBe("Forced");
+  });
+
+  it("shows a warning if the id doesn't exist", async () => {
+    // Given: --------------
+    const consoleWarnMock = jest.spyOn(console, "warn").mockImplementation();
+
+    // When: ---------------
+    await act(() => resolveDataById("Doesn't exist", appStore.getState));
+
+    // Then: ---------------
+    expect(consoleWarnMock).toHaveBeenCalledTimes(1);
+    consoleWarnMock.mockRestore();
+  });
+
+  it("shows a warning and doesn't resolve if the component was deleted", async () => {
+    // Given: --------------
+    const dispatch = appStore.getState().dispatch;
+    const consoleWarnMock = jest.spyOn(console, "warn").mockImplementation();
+
+    // When: ---------------
+    await act(async () => {
+      dispatch({ type: "remove", index: 0, zone: "Parent-1:items" });
+      resolveDataById("Child-1", appStore.getState);
+    });
+
+    // Then: ---------------
+    expect(childResolveData).toHaveBeenCalledTimes(0);
+    expect(consoleWarnMock).toHaveBeenCalledTimes(1);
+    consoleWarnMock.mockRestore();
+  });
+});

packages/core/lib/data/resolve-data-by-id.ts

@@ -0,0 +1,41 @@
+import { useAppStoreApi } from "../../store";
+import { ResolveDataTrigger } from "../../types";
+import { PuckNodeData } from "../../types/Internal";
+import { getSelectorForId } from "../get-selector-for-id";
+import { toComponent } from "./to-component";
+
+export async function resolveDataById(
+  id: string,
+  getState: ReturnType<typeof useAppStoreApi>["getState"],
+  trigger: ResolveDataTrigger = "force"
+) {
+  const node: PuckNodeData | undefined = getState().state.indexes.nodes[id];
+
+  const notFoundMsg = `Warning: Could not find component with id "${id}" to resolve its data. Component may have been removed or the id is invalid.`;
+  if (!node) {
+    console.warn(notFoundMsg);
+    return;
+  }
+
+  const resolvedResult = await getState().resolveComponentData(
+    node.data,
+    trigger
+  );
+  if (!resolvedResult.didChange) return;
+
+  const itemSelector = getSelectorForId(
+    getState().state,
+    resolvedResult.node.props.id
+  );
+  if (!itemSelector) {
+    console.warn(notFoundMsg);
+    return;
+  }
+
+  getState().dispatch({
+    type: "replace",
+    data: toComponent(resolvedResult.node),
+    destinationIndex: itemSelector.index,
+    destinationZone: itemSelector.zone,
+  });
+}

packages/core/lib/use-puck.ts

@@ -1,4 +1,4 @@
-import { Config, UserGenerics, AppState, ComponentData } from "../types";
+import { Config, UserGenerics, ResolveDataTrigger } from "../types";
 import { createContext, useContext, useEffect, useState } from "react";
 import { AppStore, useAppStoreApi } from "../store";
 import {
@@ -9,6 +9,7 @@ import { HistorySlice } from "../store/slices/history";
 import { createStore, StoreApi, useStore } from "zustand";
 import { makeStatePublic } from "./data/make-state-public";
 import { getItem, ItemSelector } from "./data/get-item";
+import { resolveDataById } from "./data/resolve-data-by-id";
 import { getSelectorForId } from "./get-selector-for-id";
 import { PuckNodeData } from "../types/Internal";
 
@@ -21,6 +22,7 @@ export type UsePuckData<
   dispatch: AppStore["dispatch"];
   getPermissions: GetPermissions<UserConfig>;
   refreshPermissions: RefreshPermissions<UserConfig>;
+  resolveDataById: (id: string, trigger?: ResolveDataTrigger) => void;
   selectedItem: G["UserComponentData"] | null;
   getItemBySelector: (
     selector: ItemSelector
@@ -47,10 +49,19 @@ type UsePuckStore<UserConfig extends Config = Config> = PuckApi<UserConfig>;
 
 type PickedStore = Pick<
   AppStore,
-  "config" | "dispatch" | "selectedItem" | "permissions" | "history" | "state"
+  | "config"
+  | "dispatch"
+  | "selectedItem"
+  | "permissions"
+  | "history"
+  | "state"
+  | "resolveComponentData"
 >;
 
-export const generateUsePuck = (store: PickedStore): UsePuckStore => {
+export const generateUsePuck = (
+  store: PickedStore,
+  getState: ReturnType<typeof useAppStoreApi>["getState"]
+): UsePuckStore => {
   const history: UsePuckStore["history"] = {
     back: store.history.back,
     forward: store.history.forward,
@@ -68,6 +79,7 @@ export const generateUsePuck = (store: PickedStore): UsePuckStore => {
     dispatch: store.dispatch,
     getPermissions: store.permissions.getPermissions,
     refreshPermissions: store.permissions.refreshPermissions,
+    resolveDataById: (id, trigger) => resolveDataById(id, getState, trigger),
     history,
     selectedItem: store.selectedItem || null,
     getItemBySelector: (selector) => getItem(selector, store.state),
@@ -100,6 +112,7 @@ const convertToPickedStore = (store: AppStore): PickedStore => {
     config: store.config,
     dispatch: store.dispatch,
     permissions: store.permissions,
+    resolveComponentData: store.resolveComponentData,
     history: store.history,
     selectedItem: store.selectedItem,
   };
@@ -113,7 +126,10 @@ export const useRegisterUsePuckStore = (
 ) => {
   const [usePuckStore] = useState(() =>
     createStore(() =>
-      generateUsePuck(convertToPickedStore(appStore.getState()))
+      generateUsePuck(
+        convertToPickedStore(appStore.getState()),
+        appStore.getState
+      )
     )
   );
 
@@ -122,7 +138,7 @@ export const useRegisterUsePuckStore = (
     return appStore.subscribe(
       (store) => convertToPickedStore(store),
       (pickedStore) => {
-        usePuckStore.setState(generateUsePuck(pickedStore));
+        usePuckStore.setState(generateUsePuck(pickedStore, appStore.getState));
       }
     );
   }, []);