@salesforce/storefront-next-runtime 0.3.1-alpha.1 → 0.4.0-alpha.0

package/README.md

@@ -46,6 +46,88 @@ Entry point for React Page Designer integration. Exports only the minimal set of
 
 CSS stylesheet containing design layer styles for Page Designer integration. Provides visual overlays, selection indicators, and design-time UI elements. Can be imported and consumed in various ways depending on your bundler configuration and build setup.
 
+### `/data-store` MRT Data Store Access
+
+Utilities and middleware for reading scoped entries from the MRT data access layer. This module intentionally exposes only key-specific helpers (initially site preferences).
+
+**Environment Variables:**
+
+- `AWS_REGION` (required): AWS region for the data store table (e.g., `us-east-1`)
+- `MOBIFY_PROPERTY_ID` (required): MRT property identifier (e.g., `abcd1234`)
+- `DEPLOY_TARGET` (required): MRT deploy target (e.g., `production`)
+
+These are managed by Managed Runtime and are not typically set by SDK consumers directly.
+
+**Provider Selection:**
+
+The runtime auto-selects the MRT provider when all MRT environment variables are present.
+If any are missing, it loads a local provider from `@salesforce/storefront-next-dev` in
+development or when explicitly allowed.
+
+Local provider opt-in outside development:
+
+- `SFNEXT_DATA_STORE_ALLOW_LOCAL` (optional): set to `true` to allow local provider
+- `CI` (optional): when set to `true`, allows the local provider
+
+Local provider environment variables (development only):
+
+- `SFNEXT_DATA_STORE_DEFAULTS` (optional): JSON map of keys to preference objects
+- `SFNEXT_DATA_STORE_WARN_ON_MISSING` (optional): set to `false` to silence warnings
+
+**Example Usage:**
+
+```typescript
+import { customSitePreferencesMiddleware, getSitePreferences } from '@salesforce/storefront-next-runtime/data-store';
+
+export const middleware = [
+  // Must run after the multi-site middleware to resolve site-specific keys.
+  customSitePreferencesMiddleware,
+  // ...other middleware
+];
+
+export const loader = ({ context }) => {
+  const sitePreferences = getSitePreferences(context);
+  return { sitePreferences };
+};
+```
+
+**Custom Middleware Usage:**
+
+If you want to read a different key or apply a custom transform, you can build your own
+middleware with `createDataStoreMiddleware` and `createDataStoreContext`.
+
+```typescript
+import {
+  createDataStoreContext,
+  createDataStoreMiddleware,
+} from '@salesforce/storefront-next-runtime/data-store';
+
+type CustomPreferences = {
+  featureFlags: Record<string, boolean>;
+};
+
+export const customPreferencesContext = createDataStoreContext<CustomPreferences>();
+
+export const customPreferencesMiddleware = createDataStoreMiddleware({
+  entryKey: 'custom-preferences',
+  context: customPreferencesContext,
+  transform: (value) => ({
+    featureFlags: value.featureFlags as Record<string, boolean>,
+  }),
+});
+
+export const loader = ({ context }) => {
+  const customPreferences = context.get(customPreferencesContext);
+  return { customPreferences };
+};
+```
+
+The site preferences middleware reads data from a site-scoped key in the data store using this format:
+
+```
+<siteid>-custom-site-preferences
+```
+
 ### `/scapi-client` SCAPI Client
 
 Type-safe, auto-generated API clients for Salesforce Commerce APIs with operation-based method names.

package/dist/DesignComponent.js

@@ -1,5 +1,5 @@
 import "./messaging-api.js";
-import { i as useDesignState, o as useComponentDiscovery } from "./DesignContext.js";
+import { a as useDesignState, i as useThrottledCallback, r as useDesignContext, s as useComponentDiscovery } from "./DesignContext.js";
 import "./modeDetection.js";
 import "./PageDesignerProvider.js";
 import { i as useRegionContext, n as useComponentContext, t as ComponentContext } from "./ComponentContext.js";
@@ -48,6 +48,27 @@ function useFocusedComponentHandler(componentId, nodeRef) {
 	]);
 }
 
+//#endregion
+//#region src/design/react/hooks/useComponentInfo.ts
+/**
+* Hook that returns the current ComponentInfo for a given component ID,
+* merging the base config with any runtime updates.
+*
+* @param componentId - The ID of the component to get info for
+* @returns The merged ComponentInfo or null if the component doesn't exist
+*/
+function useComponentInfo(componentId) {
+	const { pageDesignerConfig } = useDesignContext();
+	const { componentUpdates } = useDesignState();
+	const baseComponentInfo = pageDesignerConfig?.components?.[componentId];
+	const updates = componentUpdates?.[componentId] ?? {};
+	if (!baseComponentInfo) return null;
+	return {
+		...baseComponentInfo,
+		...updates
+	};
+}
+
 //#endregion
 //#region src/design/react/components/DesignComponent.tsx
 function DesignComponent(props) {
@@ -55,11 +76,12 @@ function DesignComponent(props) {
 	const { id = "", name, isFragment = false, isVisible = true, isLocalized = false } = designMetadata ?? {};
 	const componentId = id;
 	const componentType = useComponentType(componentId);
-	const componentName = componentType?.label || name || "Component";
+	const componentInfo = useComponentInfo(componentId);
+	const { nodeToTargetMap } = useDesignState();
+	const componentName = componentInfo?.name || componentType?.label || name || "Component";
 	const dragRef = useRef(null);
 	const { regionId } = useRegionContext() ?? {};
 	const { componentId: parentComponentId } = useComponentContext() ?? {};
-	const { nodeToTargetMap } = useDesignState();
 	const { selectedComponentId, hoveredComponentId, setSelectedComponent, setHoveredComponent, startComponentMove, setPendingComponentDragId, dragState: { pendingComponentDragId, isDragging, sourceComponentId: draggingSourceComponentId } } = useDesignState();
 	useFocusedComponentHandler(componentId, dragRef);
 	useNodeToTargetStore({
@@ -71,18 +93,21 @@ function DesignComponent(props) {
 	});
 	const discoverComponents = useComponentDiscovery({ nodeToTargetMap });
 	const isPendingDrag = pendingComponentDragId === componentId;
-	const handleMouseEnter = useCallback((event) => {
-		event.stopPropagation();
-		setHoveredComponent(componentId);
-	}, [setHoveredComponent, componentId]);
-	const handleMouseLeave = useCallback((event) => {
-		event.stopPropagation();
+	const findAndSetHoveredComponent = useCallback((x, y) => {
 		setHoveredComponent(discoverComponents({
-			x: event.clientX,
-			y: event.clientY,
+			x,
+			y,
 			filter: (entry) => entry.type === "component"
 		})[0]?.componentId ?? null);
 	}, [setHoveredComponent, discoverComponents]);
+	const handleMouseMove = useThrottledCallback((event) => {
+		event.stopPropagation();
+		findAndSetHoveredComponent(event.clientX, event.clientY);
+	}, 1e3 / 60, [findAndSetHoveredComponent]);
+	const handleMouseLeave = useCallback((event) => {
+		event.stopPropagation();
+		findAndSetHoveredComponent(event.clientX, event.clientY);
+	}, [findAndSetHoveredComponent]);
 	const handleClick = useCallback((e) => {
 		e.stopPropagation();
 		setSelectedComponent(componentId);
@@ -124,7 +149,7 @@ function DesignComponent(props) {
 		onClick: handleClick,
 		onDragOver: handleDragOver,
 		onDragStart: handleDragStart,
-		onMouseEnter: handleMouseEnter,
+		onMouseMove: handleMouseMove,
 		onMouseLeave: handleMouseLeave,
 		onMouseDown: handleMouseDown,
 		"data-component-type": componentType?.id,

package/dist/DesignComponent.js.map

@@ -1 +1 @@
-{"version":3,"file":"DesignComponent.js","names":[],"sources":["../src/design/react/hooks/useComponentDecoratorClasses.ts","../src/design/react/hooks/useFocusedComponentHandler.ts","../src/design/react/components/DesignComponent.tsx"],"sourcesContent":["/**\n * Copyright 2026 Salesforce, Inc.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nimport { useDesignState } from './useDesignState';\n\nexport function useComponentDecoratorClasses({\n    componentId,\n    isFragment,\n    isLocalized,\n}: {\n    componentId: string;\n    isFragment: boolean;\n    isLocalized: boolean;\n}): string {\n    const { selectedComponentId, hoveredComponentId, dragState } = useDesignState();\n\n    const isSelected = selectedComponentId === componentId;\n    const isHovered = !dragState.isDragging && hoveredComponentId === componentId;\n    const showFrame = (isSelected || isHovered) && !dragState.isDragging;\n    const isMoving = dragState.isDragging && dragState.sourceComponentId === componentId;\n    const isDropTarget = dragState.currentDropTarget?.componentId === componentId;\n    const dropTargetInsertType = dragState.currentDropTarget?.insertType;\n    const dropTargetAxis = dropTargetInsertType?.axis;\n\n    return [\n        'pd-design__decorator',\n        isFragment ? 'pd-design__fragment' : 'pd-design__component',\n        showFrame && 'pd-design__frame--visible',\n        isSelected && 'pd-design__decorator--selected',\n        isHovered && 'pd-design__decorator--hovered',\n        isMoving && 'pd-design__decorator--moving',\n        !isLocalized && 'pd-design__component--unlocalized',\n        isDropTarget &&\n            dropTargetAxis &&\n            dropTargetInsertType &&\n            `pd-design__drop-target__${dropTargetAxis}-${dropTargetInsertType.type}`,\n    ]\n        .filter(Boolean)\n        .join(' ');\n}\n","/**\n * Copyright 2026 Salesforce, Inc.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nimport React from 'react';\nimport { useDesignState } from './useDesignState';\n\n/**\n * Focuses a component when the focused component id matches the component id.\n * @param componentId - The id of the component to focus.\n * @param nodeRef - The ref object to the node to focus.\n */\nexport function useFocusedComponentHandler(componentId: string, nodeRef: React.RefObject<Element | null>): void {\n    const { focusedComponentId, focusComponent } = useDesignState();\n\n    React.useEffect(() => {\n        if (focusedComponentId === componentId && nodeRef.current) {\n            focusComponent(nodeRef.current);\n        }\n    }, [focusedComponentId, componentId, focusComponent, nodeRef]);\n}\n","/**\n * Copyright 2026 Salesforce, Inc.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nimport React, { useRef, useCallback } from 'react';\nimport type { ComponentDecoratorProps } from '../core/component.types';\nimport { useComponentDecoratorClasses } from '../hooks/useComponentDecoratorClasses';\nimport { useDesignState } from '../hooks/useDesignState';\nimport { useFocusedComponentHandler } from '../hooks/useFocusedComponentHandler';\nimport { useNodeToTargetStore } from '../hooks/useNodeToTargetStore';\nimport { DesignFrame } from './DesignFrame';\nimport { useRegionContext } from '../core/RegionContext';\nimport { ComponentContext, useComponentContext, type ComponentContextType } from '../core/ComponentContext';\nimport { useComponentDiscovery } from '../hooks/useComponentDiscovery';\nimport { useComponentType } from '../hooks/useComponentType';\n\nexport function DesignComponent(props: ComponentDecoratorProps<unknown>): React.JSX.Element {\n    const { designMetadata, children } = props;\n    const { id = '', name, isFragment = false, isVisible = true, isLocalized = false } = designMetadata ?? {};\n    const componentId = id;\n    const componentType = useComponentType(componentId);\n    const componentName = componentType?.label || name || 'Component';\n    const dragRef = useRef<HTMLDivElement>(null);\n    const { regionId } = useRegionContext() ?? {};\n    const { componentId: parentComponentId } = useComponentContext() ?? {};\n    const { nodeToTargetMap } = useDesignState();\n\n    const {\n        selectedComponentId,\n        hoveredComponentId,\n        setSelectedComponent,\n        setHoveredComponent,\n        startComponentMove,\n        setPendingComponentDragId,\n        dragState: { pendingComponentDragId, isDragging, sourceComponentId: draggingSourceComponentId },\n    } = useDesignState();\n\n    useFocusedComponentHandler(componentId, dragRef);\n    useNodeToTargetStore({\n        type: 'component',\n        nodeRef: dragRef,\n        parentId: parentComponentId,\n        regionId,\n        componentId,\n    });\n\n    const discoverComponents = useComponentDiscovery({\n        nodeToTargetMap,\n    });\n\n    const isPendingDrag = pendingComponentDragId === componentId;\n\n    const handleMouseEnter = useCallback(\n        (event: React.MouseEvent) => {\n            event.stopPropagation();\n            setHoveredComponent(componentId);\n        },\n        [setHoveredComponent, componentId]\n    );\n\n    const handleMouseLeave = useCallback(\n        (event: React.MouseEvent) => {\n            event.stopPropagation();\n\n            // If we hover off a component, we could still be hovering over a parent component\n            // that contains that child. In this instance, the mouse enter doesn't fire and that parent\n            // would not be highlighted. Everytime we leave a component, we check\n            // if we are hovering over a component at those coordinates. If we are,\n            // we set the hovered component to that component.\n            const components = discoverComponents({\n                x: event.clientX,\n                y: event.clientY,\n                filter: (entry) => entry.type === 'component',\n            });\n\n            setHoveredComponent(components[0]?.componentId ?? null);\n        },\n        [setHoveredComponent, discoverComponents]\n    );\n\n    const handleClick = useCallback(\n        (e: React.MouseEvent) => {\n            e.stopPropagation();\n            setSelectedComponent(componentId);\n        },\n        [setSelectedComponent, componentId]\n    );\n\n    const showFrame = [selectedComponentId, hoveredComponentId].includes(componentId) && !isDragging;\n    const isDraggable = Boolean(componentId && regionId && componentType?.id);\n\n    const classes = useComponentDecoratorClasses({\n        componentId,\n        isLocalized,\n        isFragment: Boolean(isFragment),\n    });\n\n    const context = React.useMemo<ComponentContextType>(() => ({ componentId: id, name }), [id, name]);\n\n    // Makes the component a drop target.\n    const handleDragOver = React.useCallback(\n        (event: React.DragEvent<HTMLDivElement>) => {\n            // Don't prevent propagation here.\n            // We depend on the global listener to handle the drag over event.\n            // If we are moving a component, don't let it be droppable on itself.\n            if (draggingSourceComponentId !== componentId) {\n                event.preventDefault();\n            }\n        },\n        [draggingSourceComponentId, componentId]\n    );\n\n    // When dragging, we don't consider the component as dragging until the drag start event\n    // is triggered. However, we need to mark the component as draggable on mouse down so that\n    // it can even be dragged via the native drag and drop API.\n    //\n    // If we were to mark the components as dragging on mouse down instead, a selection of a component\n    // would first remove the frame because this thinks we are dragging the component instead of selecting it.\n    // This is why it is split up into two events.\n    const handleMouseDown = React.useCallback(\n        (event: React.MouseEvent) => {\n            if (componentId) {\n                event.stopPropagation();\n                setPendingComponentDragId(componentId);\n            }\n        },\n        [componentId, setPendingComponentDragId]\n    );\n\n    const handleDragStart = React.useCallback(\n        (event: React.DragEvent) => {\n            event.stopPropagation();\n\n            if (componentId && regionId && componentType?.id) {\n                startComponentMove(componentId, regionId, componentType.id);\n            }\n        },\n        [componentId, regionId, componentType?.id, startComponentMove]\n    );\n\n    // Don't render anything if the components is hidden via visibility rules.\n    // We still want the component to be reactive in case the use changes the\n    // visibility rules or the render context.\n    if (!isVisible) {\n        return <></>;\n    }\n\n    return (\n        <div\n            ref={dragRef}\n            className={classes}\n            draggable={isPendingDrag && isDraggable}\n            onClick={handleClick}\n            onDragOver={handleDragOver}\n            onDragStart={handleDragStart}\n            onMouseEnter={handleMouseEnter}\n            onMouseLeave={handleMouseLeave}\n            onMouseDown={handleMouseDown}\n            data-component-type={componentType?.id}\n            data-testid={`design-component-${componentId}`}>\n            <div className=\"pd-design__component__drop-target\" />\n            <DesignFrame\n                showFrame={showFrame}\n                componentId={componentId}\n                localized={isLocalized}\n                name={componentName}\n                parentId={parentComponentId}\n                isMoveable={isDraggable}\n                regionId={regionId}>\n                <ComponentContext.Provider value={context}>{children}</ComponentContext.Provider>\n            </DesignFrame>\n        </div>\n    );\n}\n"],"mappings":"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"}
+{"version":3,"file":"DesignComponent.js","names":[],"sources":["../src/design/react/hooks/useComponentDecoratorClasses.ts","../src/design/react/hooks/useFocusedComponentHandler.ts","../src/design/react/hooks/useComponentInfo.ts","../src/design/react/components/DesignComponent.tsx"],"sourcesContent":["/**\n * Copyright 2026 Salesforce, Inc.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nimport { useDesignState } from './useDesignState';\n\nexport function useComponentDecoratorClasses({\n    componentId,\n    isFragment,\n    isLocalized,\n}: {\n    componentId: string;\n    isFragment: boolean;\n    isLocalized: boolean;\n}): string {\n    const { selectedComponentId, hoveredComponentId, dragState } = useDesignState();\n\n    const isSelected = selectedComponentId === componentId;\n    const isHovered = !dragState.isDragging && hoveredComponentId === componentId;\n    const showFrame = (isSelected || isHovered) && !dragState.isDragging;\n    const isMoving = dragState.isDragging && dragState.sourceComponentId === componentId;\n    const isDropTarget = dragState.currentDropTarget?.componentId === componentId;\n    const dropTargetInsertType = dragState.currentDropTarget?.insertType;\n    const dropTargetAxis = dropTargetInsertType?.axis;\n\n    return [\n        'pd-design__decorator',\n        isFragment ? 'pd-design__fragment' : 'pd-design__component',\n        showFrame && 'pd-design__frame--visible',\n        isSelected && 'pd-design__decorator--selected',\n        isHovered && 'pd-design__decorator--hovered',\n        isMoving && 'pd-design__decorator--moving',\n        !isLocalized && 'pd-design__component--unlocalized',\n        isDropTarget &&\n            dropTargetAxis &&\n            dropTargetInsertType &&\n            `pd-design__drop-target__${dropTargetAxis}-${dropTargetInsertType.type}`,\n    ]\n        .filter(Boolean)\n        .join(' ');\n}\n","/**\n * Copyright 2026 Salesforce, Inc.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nimport React from 'react';\nimport { useDesignState } from './useDesignState';\n\n/**\n * Focuses a component when the focused component id matches the component id.\n * @param componentId - The id of the component to focus.\n * @param nodeRef - The ref object to the node to focus.\n */\nexport function useFocusedComponentHandler(componentId: string, nodeRef: React.RefObject<Element | null>): void {\n    const { focusedComponentId, focusComponent } = useDesignState();\n\n    React.useEffect(() => {\n        if (focusedComponentId === componentId && nodeRef.current) {\n            focusComponent(nodeRef.current);\n        }\n    }, [focusedComponentId, componentId, focusComponent, nodeRef]);\n}\n","/**\n * Copyright 2026 Salesforce, Inc.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nimport type { ComponentInfo } from '../../messaging-api';\nimport { useDesignContext } from '../context/DesignContext';\nimport { useDesignState } from './useDesignState';\n\n/**\n * Hook that returns the current ComponentInfo for a given component ID,\n * merging the base config with any runtime updates.\n *\n * @param componentId - The ID of the component to get info for\n * @returns The merged ComponentInfo or null if the component doesn't exist\n */\nexport function useComponentInfo(componentId: string): ComponentInfo | null {\n    const { pageDesignerConfig } = useDesignContext();\n    const { componentUpdates } = useDesignState();\n    const baseComponentInfo = pageDesignerConfig?.components?.[componentId];\n    const updates = componentUpdates?.[componentId] ?? {};\n\n    if (!baseComponentInfo) {\n        return null;\n    }\n\n    return { ...baseComponentInfo, ...updates };\n}\n","/**\n * Copyright 2026 Salesforce, Inc.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nimport React, { useRef, useCallback } from 'react';\nimport type { ComponentDecoratorProps } from '../core/component.types';\nimport { useComponentDecoratorClasses } from '../hooks/useComponentDecoratorClasses';\nimport { useDesignState } from '../hooks/useDesignState';\nimport { useFocusedComponentHandler } from '../hooks/useFocusedComponentHandler';\nimport { useNodeToTargetStore } from '../hooks/useNodeToTargetStore';\nimport { DesignFrame } from './DesignFrame';\nimport { useRegionContext } from '../core/RegionContext';\nimport { ComponentContext, useComponentContext, type ComponentContextType } from '../core/ComponentContext';\nimport { useComponentDiscovery } from '../hooks/useComponentDiscovery';\nimport { useComponentType } from '../hooks/useComponentType';\nimport { useThrottledCallback } from '../hooks/useThrottledCallback';\nimport { useComponentInfo } from '../hooks/useComponentInfo';\n\nexport function DesignComponent(props: ComponentDecoratorProps<unknown>): React.JSX.Element {\n    const { designMetadata, children } = props;\n    const { id = '', name, isFragment = false, isVisible = true, isLocalized = false } = designMetadata ?? {};\n    const componentId = id;\n    const componentType = useComponentType(componentId);\n    const componentInfo = useComponentInfo(componentId);\n    const { nodeToTargetMap } = useDesignState();\n\n    const componentName = componentInfo?.name || componentType?.label || name || 'Component';\n    const dragRef = useRef<HTMLDivElement>(null);\n    const { regionId } = useRegionContext() ?? {};\n    const { componentId: parentComponentId } = useComponentContext() ?? {};\n\n    const {\n        selectedComponentId,\n        hoveredComponentId,\n        setSelectedComponent,\n        setHoveredComponent,\n        startComponentMove,\n        setPendingComponentDragId,\n        dragState: { pendingComponentDragId, isDragging, sourceComponentId: draggingSourceComponentId },\n    } = useDesignState();\n\n    useFocusedComponentHandler(componentId, dragRef);\n    useNodeToTargetStore({\n        type: 'component',\n        nodeRef: dragRef,\n        parentId: parentComponentId,\n        regionId,\n        componentId,\n    });\n\n    const discoverComponents = useComponentDiscovery({\n        nodeToTargetMap,\n    });\n\n    const isPendingDrag = pendingComponentDragId === componentId;\n    const findAndSetHoveredComponent = useCallback(\n        (x: number, y: number) => {\n            // If we hover off a component, we could still be hovering over a parent component\n            // that contains that child. In this instance, the mouse enter doesn't fire and that parent\n            // would not be highlighted. Everytime we leave a component, we check\n            // if we are hovering over a component at those coordinates. If we are,\n            // we set the hovered component to that component.\n            const components = discoverComponents({\n                x,\n                y,\n                filter: (entry) => entry.type === 'component',\n            });\n\n            setHoveredComponent(components[0]?.componentId ?? null);\n        },\n        [setHoveredComponent, discoverComponents]\n    );\n\n    const handleMouseMove = useThrottledCallback(\n        (event: React.MouseEvent) => {\n            event.stopPropagation();\n            findAndSetHoveredComponent(event.clientX, event.clientY);\n        },\n        1000 / 60, // 60 FPS\n        [findAndSetHoveredComponent]\n    );\n\n    const handleMouseLeave = useCallback(\n        (event: React.MouseEvent) => {\n            event.stopPropagation();\n            findAndSetHoveredComponent(event.clientX, event.clientY);\n        },\n        [findAndSetHoveredComponent]\n    );\n\n    const handleClick = useCallback(\n        (e: React.MouseEvent) => {\n            e.stopPropagation();\n            setSelectedComponent(componentId);\n        },\n        [setSelectedComponent, componentId]\n    );\n\n    const showFrame = [selectedComponentId, hoveredComponentId].includes(componentId) && !isDragging;\n    const isDraggable = Boolean(componentId && regionId && componentType?.id);\n\n    const classes = useComponentDecoratorClasses({\n        componentId,\n        isLocalized,\n        isFragment: Boolean(isFragment),\n    });\n\n    const context = React.useMemo<ComponentContextType>(() => ({ componentId: id, name }), [id, name]);\n\n    // Makes the component a drop target.\n    const handleDragOver = React.useCallback(\n        (event: React.DragEvent<HTMLDivElement>) => {\n            // Don't prevent propagation here.\n            // We depend on the global listener to handle the drag over event.\n            // If we are moving a component, don't let it be droppable on itself.\n            if (draggingSourceComponentId !== componentId) {\n                event.preventDefault();\n            }\n        },\n        [draggingSourceComponentId, componentId]\n    );\n\n    // When dragging, we don't consider the component as dragging until the drag start event\n    // is triggered. However, we need to mark the component as draggable on mouse down so that\n    // it can even be dragged via the native drag and drop API.\n    //\n    // If we were to mark the components as dragging on mouse down instead, a selection of a component\n    // would first remove the frame because this thinks we are dragging the component instead of selecting it.\n    // This is why it is split up into two events.\n    const handleMouseDown = React.useCallback(\n        (event: React.MouseEvent) => {\n            if (componentId) {\n                event.stopPropagation();\n                setPendingComponentDragId(componentId);\n            }\n        },\n        [componentId, setPendingComponentDragId]\n    );\n\n    const handleDragStart = React.useCallback(\n        (event: React.DragEvent) => {\n            event.stopPropagation();\n\n            if (componentId && regionId && componentType?.id) {\n                startComponentMove(componentId, regionId, componentType.id);\n            }\n        },\n        [componentId, regionId, componentType?.id, startComponentMove]\n    );\n\n    // Don't render anything if the components is hidden via visibility rules.\n    // We still want the component to be reactive in case the use changes the\n    // visibility rules or the render context.\n    if (!isVisible) {\n        return <></>;\n    }\n\n    return (\n        <div\n            ref={dragRef}\n            className={classes}\n            draggable={isPendingDrag && isDraggable}\n            onClick={handleClick}\n            onDragOver={handleDragOver}\n            onDragStart={handleDragStart}\n            onMouseMove={handleMouseMove}\n            onMouseLeave={handleMouseLeave}\n            onMouseDown={handleMouseDown}\n            data-component-type={componentType?.id}\n            data-testid={`design-component-${componentId}`}>\n            <div className=\"pd-design__component__drop-target\" />\n            <DesignFrame\n                showFrame={showFrame}\n                componentId={componentId}\n                localized={isLocalized}\n                name={componentName}\n                parentId={parentComponentId}\n                isMoveable={isDraggable}\n                regionId={regionId}>\n                <ComponentContext.Provider value={context}>{children}</ComponentContext.Provider>\n            </DesignFrame>\n        </div>\n    );\n}\n"],"mappings":"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"}

package/dist/DesignContext.js

@@ -510,6 +510,48 @@ function useDragInteraction({ nodeToTargetMap }) {
 	};
 }
 
+//#endregion
+//#region src/design/react/hooks/useComponentUpdateInteraction.ts
+/**
+* Custom hook that manages component update state and handles
+* client-host communication for component update events.
+*
+* Listens for ComponentUpdated events from the host and maintains
+* a map of component IDs to their updated data.
+*
+* @returns Component update state
+*/
+function useComponentUpdateInteraction() {
+	const { state: componentUpdates } = useInteraction({
+		initialState: {},
+		eventHandlers: {
+			ClientAcknowledged: { handler: (event, setState) => {
+				const initialUpdates = {};
+				Object.entries(event.components).forEach(([id, componentInfo]) => {
+					if (componentInfo.name) initialUpdates[id] = { name: componentInfo.name };
+				});
+				if (Object.keys(initialUpdates).length > 0) setState((prev) => ({
+					...prev,
+					...initialUpdates
+				}));
+			} },
+			ComponentUpdated: { handler: (event, setState) => {
+				setState((prev) => {
+					const componentId = event.componentId;
+					const updated = { ...prev[componentId] || {} };
+					if (event.changeType === "name") updated.name = event.newValue;
+					else if (event.changeType === "visibility") updated.visibility = event.newValue;
+					return {
+						...prev,
+						[componentId]: updated
+					};
+				});
+			} }
+		}
+	});
+	return { componentUpdates };
+}
+
 //#endregion
 //#region src/design/react/context/DesignStateContext.tsx
 const DesignStateContext = React.createContext(null);
@@ -522,6 +564,7 @@ const DesignStateProvider = ({ children }) => {
 	});
 	const focusInteraction = useFocusInteraction({ setSelectedComponent: selectInteraction.setSelectedComponent });
 	const scrollInteraction = useScrollInteraction();
+	const componentUpdateInteraction = useComponentUpdateInteraction();
 	const nodeToTargetMap = React.useMemo(() => /* @__PURE__ */ new WeakMap(), []);
 	const dragInteraction = useDragInteraction({ nodeToTargetMap });
 	const state = React.useMemo(() => ({
@@ -531,6 +574,7 @@ const DesignStateProvider = ({ children }) => {
 		...focusInteraction,
 		...dragInteraction,
 		...scrollInteraction,
+		...componentUpdateInteraction,
 		nodeToTargetMap
 	}), [
 		deleteInteraction,
@@ -539,7 +583,8 @@ const DesignStateProvider = ({ children }) => {
 		focusInteraction,
 		dragInteraction,
 		nodeToTargetMap,
-		scrollInteraction
+		scrollInteraction,
+		componentUpdateInteraction
 	]);
 	return /* @__PURE__ */ jsx(DesignStateContext.Provider, {
 		value: state,
@@ -765,5 +810,5 @@ DesignProvider.defaultProps = {
 const useDesignContext = () => React.useContext(DesignContext);
 
 //#endregion
-export { isComponentTypeAllowedInRegion as a, useDesignState as i, DesignProvider as n, useComponentDiscovery as o, useDesignContext as r, DesignContext as t };
+export { useDesignState as a, useThrottledCallback as i, DesignProvider as n, isComponentTypeAllowedInRegion as o, useDesignContext as r, useComponentDiscovery as s, DesignContext as t };
 //# sourceMappingURL=DesignContext.js.map