@hubspot/ui-extensions 0.12.2 → 0.12.4

package/dist/shared/types/pages/components/page-header.d.ts

@@ -0,0 +1,82 @@
+import type { ReactElement, ReactNode } from 'react';
+import type { ReactionsHandler } from '../../reactions.ts';
+import type { BaseComponentProps, ExtensionEvent } from '../../shared.ts';
+/**
+ * The props type for [PageHeader](https://developers.hubspot.com/docs/apps/developer-platform/add-features/ui-extensibility/ui-components/app-page-components/page-header).
+ *
+ * @category Component Props
+ */
+export interface PageHeaderProps extends BaseComponentProps {
+    /**
+     * Sets the content that will render inside the component. Can contain only <code>PageHeader.PrimaryAction</code> and/or <code>PageHeader.SecondaryActions</code> components.
+     */
+    children: ReactElement<PageHeaderPrimaryActionProps> | ReactElement<PageHeaderSecondaryActionsProps>;
+}
+/**
+ * The props type for [PageHeader.PrimaryAction](https://developers.hubspot.com/docs/apps/developer-platform/add-features/ui-extensibility/ui-components/app-page-components/page-header#pageheader-primaryaction).
+ *
+ * @category Component Props
+ */
+export interface PageHeaderPrimaryActionProps extends BaseComponentProps {
+    /**
+     * Must be a <code>PageHeader.PageLink</code> component (for internal app pages) or a <code>PageHeader.Link</code> component (for URLs outside your app). No other component types are supported.
+     */
+    children: ReactNode;
+}
+/**
+ * The props type for [PageHeader.SecondaryActions](https://developers.hubspot.com/docs/apps/developer-platform/add-features/ui-extensibility/ui-components/app-page-components/page-header#pageheader-secondaryactions).
+ *
+ * @category Component Props
+ */
+export interface PageHeaderSecondaryActionsProps extends BaseComponentProps {
+    /**
+     * Must contain one or more <code>PageHeader.PageLink</code> component (for internal app pages) or a <code>PageHeader.Link</code> component (for URLs outside your app). No other component types are supported.
+     */
+    children: ReactNode;
+}
+/**
+ * The props type for [PageHeader.Link](https://developers.hubspot.com/docs/apps/developer-platform/add-features/ui-extensibility/ui-components/app-page-components/page-header#pageheader-link).
+ *
+ * @category Component Props
+ */
+export interface PageHeaderLinkProps extends BaseComponentProps {
+    /**
+     * A URL that will be opened when the button is clicked. If the value is a URL external to `hubspot.com` it will be opened in a new tab.
+     */
+    href?: string;
+    /**
+     * A function that will be invoked when the button is clicked. Do not use this function for submitting a form; use Form's `onSubmit` function instead.
+     *
+     * @event
+     */
+    onClick?: ReactionsHandler<ExtensionEvent>;
+    /**
+     * Determines whether or not the button should be disabled.
+     */
+    disabled?: boolean;
+    /**
+     * The visible label of the link button. This prop is passed implicitly by providing sub-components.
+     */
+    children: ReactNode;
+}
+/**
+ * The props type for [PageHeader.PageLink](https://developers.hubspot.com/docs/apps/developer-platform/add-features/ui-extensibility/ui-components/app-page-components/page-header#pageheader-pagelink).
+ *
+ * @category Component Props
+ */
+export interface PageHeaderPageLinkProps extends BaseComponentProps {
+    /**
+     * The path to navigate to when the link is clicked. Supports path parameters (e.g. `/view-contact/:contactId`).
+     */
+    to: string;
+    /**
+     * Values for path parameters and query string entries.
+     * Parameters matching `:paramName` tokens in `to` are substituted into the path.
+     * Any remaining parameters are appended as query string entries.
+     */
+    params?: Record<string, string>;
+    /**
+     * The visible label of the link button. This prop is passed implicitly by providing sub-components.
+     */
+    children: ReactNode;
+}

package/dist/shared/types/pages/components/page-header.js

@@ -0,0 +1 @@
+export {};

package/dist/shared/types/pages/components/page-link.d.ts

@@ -0,0 +1,25 @@
+import type { ReactNode } from 'react';
+import type { BaseComponentProps } from '../../shared.ts';
+/**
+ * The props type for [PageLink](https://developers.hubspot.com/docs/apps/developer-platform/add-features/ui-extensibility/ui-components/app-page-components/page-link).
+ *
+ * @category Component Props
+ */
+export interface PageLinkProps extends BaseComponentProps {
+    /**
+     * The path to navigate to. Can be a simple path (e.g., <code>"/docs"</code>) or a path with parameters
+     * (e.g., <code>"/view-contact/:contactId"</code>). When using path parameters, provide the parameter
+     * values in the <code>params</code> prop.
+     */
+    to: string;
+    /**
+     * Values for path parameters and query string entries.
+     * Parameters matching `:paramName` tokens in `to` are substituted into the path.
+     * Any remaining parameters are appended as query string entries.
+     */
+    params?: Record<string, string>;
+    /**
+     * The content to display inside the link.
+     */
+    children: ReactNode;
+}

package/dist/shared/types/pages/components/page-link.js

@@ -0,0 +1 @@
+export {};

package/dist/shared/types/pages/components/page-routes.d.ts

@@ -0,0 +1,115 @@
+import type { ComponentType, ReactNode } from 'react';
+import type { EmptyProps } from '../../shared.ts';
+/**
+ * The props type for the layout component of [PageRoutes](https://developers.hubspot.com/docs/apps/developer-platform/add-features/ui-extensibility/ui-components/app-page-components/page-routes#pageroutes).
+ */
+export interface PageRoutesLayoutProps {
+    /**
+     * The content to render inside the layout.
+     */
+    children: ReactNode;
+}
+interface BaseRouteProps {
+    /**
+     * The component to render when the route is matched.
+     */
+    component: ComponentType<EmptyProps>;
+    /**
+     * A unique identifier for the route.
+     */
+    id?: string;
+}
+/**
+ * The props type for [PageRoutes.IndexRoute](https://developers.hubspot.com/docs/apps/developer-platform/add-features/ui-extensibility/ui-components/app-page-components/page-routes#pageroutes-indexroute).
+ */
+export type IndexRouteProps = BaseRouteProps;
+/**
+ * The props type for [PageRoutes.Route](https://developers.hubspot.com/docs/apps/developer-platform/add-features/ui-extensibility/ui-components/app-page-components/page-routes#pageroutes-route).
+ */
+export interface RouteProps extends BaseRouteProps {
+    /**
+     * The path pattern of the route to match.
+     */
+    path: string;
+}
+/**
+ * The props type for [PageRoutes.AnyRoute](https://developers.hubspot.com/docs/apps/developer-platform/add-features/ui-extensibility/ui-components/app-page-components/page-routes#pageroutes-anyroute).
+ */
+export type AnyRouteProps = BaseRouteProps;
+/**
+ * The component type for the layout component of [PageRoutes](https://developers.hubspot.com/docs/apps/developer-platform/add-features/ui-extensibility/ui-components/app-page-components/page-routes#pageroutes).
+ */
+export type PageRoutesLayoutComponent = ComponentType<PageRoutesLayoutProps>;
+/**
+ * The props type for [PageRoutes](https://developers.hubspot.com/docs/apps/developer-platform/add-features/ui-extensibility/ui-components/app-page-components/page-routes#pageroutes).
+ */
+export interface PageRoutesProps {
+    /**
+     * The path pattern of the route to include with all nested routes.
+     */
+    path?: string;
+    /**
+     * The component to render for the layout of the page routes.
+     */
+    layoutComponent?: PageRoutesLayoutComponent;
+    /**
+     * The nested route definitions.
+     */
+    children: ReactNode;
+}
+/**
+ * Used as a descriptor for a collection of page routes.
+ *
+ * Example usage:
+ *
+ * ```tsx
+ * const PageRouter = createPageRouter(<PageRoutes>
+ *   <PageRoutes.IndexRoute component={HomePage} />
+ *   <PageRoutes.Route path="/docs" component={DocsPage} />
+ *   <PageRoutes.AnyRoute component={NotFoundPage} />
+ * </PageRoutes>);
+ * ```
+ *
+ * See [PageRoutes](https://developers.hubspot.com/docs/apps/developer-platform/add-features/ui-extensibility/ui-components/app-page-components/page-routes#pageroutes) for more information.
+ *
+ * @experimental This component is experimental. Avoid using it in production due to potential breaking changes. Your feedback is valuable for improvements. Stay tuned for updates.
+ */
+export interface PageRoutesComponent {
+    (props: PageRoutesProps): null;
+    /**
+     * Used as a descriptor for an index (i.e., "/") route.
+     *
+     * Example usage:
+     *
+     * ```tsx
+     * <PageRoutes.IndexRoute component={HomePage} />
+     * ```
+     *
+     * @experimental This component is experimental. Avoid using it in production due to potential breaking changes. Your feedback is valuable for improvements. Stay tuned for updates.
+     */
+    IndexRoute: (props: IndexRouteProps) => null;
+    /**
+     * Used as a descriptor for a route with a path pattern.
+     *
+     * Example usage:
+     *
+     * ```tsx
+     * <PageRoutes.Route path="/docs" component={DocsPage} />
+     * ```
+     * @experimental This component is experimental. Avoid using it in production due to potential breaking changes. Your feedback is valuable for improvements. Stay tuned for updates.
+     */
+    Route: (props: RouteProps) => null;
+    /**
+     * Used as a descriptor for a route that matches any path.
+     *
+     * Example usage:
+     *
+     * ```tsx
+     * <PageRoutes.AnyRoute component={NotFoundPage} />
+     * ```
+     *
+     * @experimental This component is experimental. Avoid using it in production due to potential breaking changes. Your feedback is valuable for improvements. Stay tuned for updates.
+     */
+    AnyRoute: (props: AnyRouteProps) => null;
+}
+export {};

package/dist/shared/types/pages/components/page-routes.js

@@ -0,0 +1 @@
+export {};

package/dist/shared/types/pages/components/page-title.d.ts

@@ -0,0 +1,12 @@
+import type { BaseComponentProps } from '../../shared.ts';
+/**
+ * The props type for [PageTitle](https://developers.hubspot.com/docs/apps/developer-platform/add-features/ui-extensibility/ui-components/app-page-components/page-title).
+ *
+ * @category Component Props
+ */
+export interface PageTitleProps extends BaseComponentProps {
+    /**
+     * The text to display as the page heading. Also sets the browser tab title.
+     */
+    children: string;
+}

package/dist/shared/types/pages/components/page-title.js

@@ -0,0 +1 @@
+export {};

package/dist/shared/types/pages/index.d.ts

@@ -0,0 +1 @@
+export type * from './components/index.ts';

package/dist/shared/types/pages/index.js

@@ -0,0 +1 @@
+export {};

package/dist/shared/types/pages.d.ts

@@ -0,0 +1 @@
+export type * from './pages/index.ts';

package/dist/shared/types/pages.js

@@ -0,0 +1 @@
+export {};

package/dist/shared/types/shared.d.ts

@@ -1,4 +1,4 @@
-import type { ReactElement, ComponentType, ReactNode } from 'react';
+import type { ComponentType, ReactElement, ReactNode } from 'react';
 export type UnknownComponentProps = Record<string, any>;
 /**
  * Represents a HubSpot-provided React component.
@@ -255,3 +255,17 @@ export interface BaseComponentProps {
      */
     testId?: string;
 }
+export type EmptyProps = Record<string, never>;
+/**
+ * Represents the current page location and its parameters. This is used to support app page routing.
+ */
+export interface AppPageLocation {
+    path: string;
+    params: Record<string, string>;
+}
+/**
+ * The props type for a React fragment component.
+ */
+export interface ReactFragmentProps {
+    children?: ReactNode | undefined;
+}

package/dist/shared/types/worker-globals.d.ts

@@ -1,6 +1,7 @@
-import { Logger } from './logger.ts';
-import { HubspotExtendFunction } from './extend.ts';
-import type { ExtensionPoints, ExtensionPointApiContext, ExtensionPointApiActions, ExtensionPointFullApi } from './extension-points.ts';
+import type { HubspotExtendFunction } from './extend.ts';
+import type { ExtensionPointApiActions, ExtensionPointApiContext, ExtensionPointFullApi, ExtensionPoints } from './extension-points.ts';
+import type { Logger } from './logger.ts';
+import type { AppPageLocation } from './shared.ts';
 export interface WorkersApi {
     /**
      * Hook added to worker globals so customer code can access extension context at runtime.
@@ -14,6 +15,10 @@ export interface WorkersApi {
      * Hook added to worker globals so customer code can access extension API at runtime.
      */
     useExtensionApi: <ExtensionPoint extends keyof ExtensionPoints>() => ExtensionPointFullApi<ExtensionPoint>;
+    /**
+     * Hook added to worker globals so page router can access the current app page location at runtime.
+     */
+    useAppPageLocation: () => AppPageLocation;
 }
 export interface WorkerGlobalsInternal {
     /**

package/dist/shared/utils/remote-component-registry.d.ts

@@ -1,4 +1,4 @@
-import { HubSpotReactComponent, HubSpotReactFragmentProp, UnknownComponentProps } from '../types/shared.ts';
+import type { HubSpotReactComponent, HubSpotReactFragmentProp, UnknownComponentProps } from '../types/shared.ts';
 /**
  * Options for creating a remote React component.
  */

package/dist/testing/__tests__/isMatch.spec.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { describe, expect, it } from 'vitest';
 import { Alert, Button } from "../../index.js";
-import { createRenderer, isMatch, isRenderedFragmentNode, } from "../index.js";
+import { createRenderer, isMatch, isRenderedFragmentNode } from "../index.js";
 describe('isMatch()', () => {
     describe('isMatch() utility function', () => {
         it('should allow assertions against a mix of text and element nodes', () => {

package/dist/testing/__tests__/mocks.runServerlessFunction.spec.js

@@ -1,6 +1,6 @@
 import { describe, it } from 'vitest';
+import { ServerlessExecutionStatus } from "../../shared/types/http-requests.js";
 import { createRenderer } from "../index.js";
-import { ServerlessExecutionStatus, } from "../../shared/types/http-requests.js";
 describe('mock runServerlessFunction', () => {
     it('should provide the ability to spy on the runServerlessFunction function', async () => {
         const { mocks } = createRenderer('crm.record.tab');

package/dist/testing/__tests__/mocks.useAssociations.spec.js

@@ -1,8 +1,8 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { describe, expect, it, vi } from 'vitest';
-import { Text, Button } from "../../index.js";
-import { createRenderer } from "../index.js";
 import { useAssociations } from "../../crm/index.js";
+import { Button, Text } from "../../index.js";
+import { createRenderer } from "../index.js";
 function MyComponent() {
     const { results, isLoading, isRefetching, error, refetch } = useAssociations({
         toObjectType: '0-1',

package/dist/testing/__tests__/mocks.useCrmProperties.spec.js

@@ -1,8 +1,8 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { describe, expect, it, vi } from 'vitest';
-import { Text, Button } from "../../index.js";
-import { createRenderer } from "../index.js";
 import { useCrmProperties } from "../../crm/index.js";
+import { Button, Text } from "../../index.js";
+import { createRenderer } from "../index.js";
 function MyComponent() {
     const { properties, isLoading, isRefetching, error, refetch } = useCrmProperties(['firstname', 'lastname']);
     if (isLoading) {

package/dist/testing/__tests__/mocks.useExtensionActions.spec.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
-import { createRenderer } from "../index.js";
 import { useExtensionActions } from "../../hooks/useExtensionActions.js";
 import { Button } from "../../index.js";
+import { createRenderer } from "../index.js";
 function MyActionsCrmComponent() {
     const actions = useExtensionActions();
     return (_jsxs(_Fragment, { children: [_jsx(Button, { testId: "reloadButton", onClick: () => actions.reloadPage(), children: "Reload Page" }), _jsx(Button, { testId: "fetchButton", onClick: () => {

package/dist/testing/__tests__/mocks.useExtensionApi.spec.js

@@ -1,8 +1,8 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { describe, expect, it } from 'vitest';
+import { useExtensionApi } from "../../hooks/useExtensionApi.js";
 import { Button, Text } from "../../index.js";
 import { createRenderer } from "../index.js";
-import { useExtensionApi } from "../../hooks/useExtensionApi.js";
 function MyComponent() {
     const { context } = useExtensionApi();
     return (_jsxs(_Fragment, { children: [_jsx(Text, { testId: "location-text", children: context.location }), _jsx(Text, { testId: "user-email", children: context.user.email }), _jsx(Text, { testId: "user-firstName", children: context.user.firstName }), _jsx(Text, { testId: "user-lastName", children: context.user.lastName }), _jsx(Text, { testId: "portal-id", children: context.portal.id }), _jsx(Text, { testId: "portal-timezone", children: context.portal.timezone }), 'crm' in context && (_jsxs(_Fragment, { children: [_jsx(Text, { testId: "crm-objectId", children: context.crm.objectId }), _jsx(Text, { testId: "crm-objectTypeId", children: context.crm.objectTypeId })] }))] }));

package/dist/testing/__tests__/mocks.useExtensionContext.spec.js

@@ -1,8 +1,8 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { describe, expect, it } from 'vitest';
+import { useExtensionContext } from "../../hooks/useExtensionContext.js";
 import { Text } from "../../index.js";
 import { createRenderer } from "../index.js";
-import { useExtensionContext } from "../../hooks/useExtensionContext.js";
 function MyComponent() {
     const context = useExtensionContext();
     return (_jsxs(_Fragment, { children: [_jsx(Text, { testId: "location-text", children: context.location }), _jsx(Text, { testId: "user-email", children: context.user.email }), _jsx(Text, { testId: "user-firstName", children: context.user.firstName }), _jsx(Text, { testId: "user-lastName", children: context.user.lastName }), _jsx(Text, { testId: "portal-id", children: context.portal.id }), _jsx(Text, { testId: "portal-timezone", children: context.portal.timezone }), 'crm' in context && (_jsxs(_Fragment, { children: [_jsx(Text, { testId: "crm-objectId", children: context.crm.objectId }), _jsx(Text, { testId: "crm-objectTypeId", children: context.crm.objectTypeId })] }))] }));

package/dist/testing/internal/convert.d.ts

@@ -1,4 +1,4 @@
-import { type RemoteRoot } from '@remote-ui/core';
+import type { RemoteRoot } from '@remote-ui/core';
 import type { RenderedRootNodeInternal } from './types-internal.ts';
 /**
  * Converts a remote root node to a rendered root node. After conversion, the rendered root node will

package/dist/testing/internal/convert.js

@@ -1,13 +1,12 @@
-import { KIND_COMPONENT, KIND_FRAGMENT, KIND_TEXT, } from '@remote-ui/core';
+import { KIND_COMPONENT, KIND_FRAGMENT, KIND_TEXT } from '@remote-ui/core';
+import { __hubSpotComponentRegistry } from "../../shared/remoteComponents.js";
+import { isRenderedTextNode } from "../type-utils.js";
+import { EMPTY_RENDERED_CHILD_NODES } from "./constants.js";
 import { createElementNode } from "./element.js";
 import { DuplicateTestIdError, InvalidFragmentPropArrayError, } from "./errors.js";
 import { createFragmentNode } from "./fragment.js";
 import { createTextNode } from "./text.js";
-import { __hubSpotComponentRegistry } from "../../shared/remoteComponents.js";
-import { isRenderedTextNode } from "../type-utils.js";
-import { EMPTY_RENDERED_CHILD_NODES } from "./constants.js";
 import { asRenderedParentNode } from "./type-utils-internal.js";
-/* eslint-disable @typescript-eslint/no-use-before-define */
 /**
  * Converts a remote props object to a props object that can be attached to a rendered element node.
  *

package/dist/testing/internal/debug.d.ts

@@ -1,4 +1,4 @@
-import { RenderedNode } from '../types.ts';
+import type { RenderedNode } from '../types.ts';
 /**
  * Logs a rendered node tree to the console for debugging purposes.
  *

package/dist/testing/internal/element.d.ts

@@ -1,5 +1,5 @@
 import type { UnknownComponentProps } from '../../shared/types/shared.ts';
-import { RenderedElementNode } from '../types.ts';
+import type { RenderedElementNode } from '../types.ts';
 import type { RenderedDocumentInternal } from './types-internal.ts';
 /**
  * Creates a rendered element node.

package/dist/testing/internal/errors.d.ts

@@ -1,5 +1,5 @@
-import { RenderedElementNode, RenderedParentNode } from '../types.ts';
-import { RenderedRootNodeInternal } from './types-internal.ts';
+import type { RenderedElementNode, RenderedParentNode } from '../types.ts';
+import type { RenderedRootNodeInternal } from './types-internal.ts';
 /**
  * Thrown when trying to trigger an event that has a handler prop that is not a function.
  */

package/dist/testing/internal/fragment.d.ts

@@ -1,4 +1,4 @@
-import { RenderedFragmentNode } from '../types.ts';
+import type { RenderedFragmentNode } from '../types.ts';
 import type { RenderedDocumentInternal } from './types-internal.ts';
 /**
  * Creates a rendered fragment node.

package/dist/testing/internal/match.d.ts

@@ -1,5 +1,5 @@
-import { UnknownComponentProps } from '../../shared/types/shared.ts';
-import { ElementMatcher, RenderedElementNode } from '../types.ts';
+import type { UnknownComponentProps } from '../../shared/types/shared.ts';
+import type { ElementMatcher, RenderedElementNode } from '../types.ts';
 /**
  * Checks if the element matches the matcher.
  *

package/dist/testing/internal/mocks/index.d.ts

@@ -1,12 +1,20 @@
-import { RendererSpies } from '../../types.ts';
-import { RendererMocksInternal } from '../types-internal.ts';
-import { ExtensionPointLocation } from '../../../shared/types/extension-points.ts';
+import { type useAppPageLocation } from '../../../experimental/pages/internal/useAppPageLocation.tsx';
+import type { ExtensionPointLocation } from '../../../shared/types/extension-points.ts';
+import type { RendererMocks } from '../../types.ts';
+import { type MocksAppPageLocationStore } from './mock-app-page-location.tsx';
 /**
  * An object containing the mocks and spies.
  */
-export interface MocksWithSpies<TExtensionPointLocation extends ExtensionPointLocation> {
-    mocks: RendererMocksInternal<TExtensionPointLocation>;
-    spies: RendererSpies<TExtensionPointLocation>;
+export interface RendererMocksContext {
+    /**
+     * The mocks object provided by the testing utilities.
+     */
+    mocks: RendererMocks<ExtensionPointLocation>;
+    /**
+     * The app page location store.
+     */
+    appPageLocationStore: MocksAppPageLocationStore;
+    useAppPageLocation: typeof useAppPageLocation;
 }
 /**
  * Creates a set of mocks and spies for the various functions such as the `useCrmProperties` and `useAssociations`
@@ -14,4 +22,4 @@ export interface MocksWithSpies<TExtensionPointLocation extends ExtensionPointLo
  *
  * @returns An object containing the mocks and spies.
  */
-export declare const createMocksWithSpies: <TExtensionPointLocation extends ExtensionPointLocation>(extensionPointLocation: TExtensionPointLocation) => MocksWithSpies<TExtensionPointLocation>;
+export declare const createRendererMocksContext: <TExtensionPointLocation extends ExtensionPointLocation>(extensionPointLocation: TExtensionPointLocation) => RendererMocksContext;

package/dist/testing/internal/mocks/index.js

@@ -1,6 +1,8 @@
+import { act as reactAct, useSyncExternalStore } from 'react';
 import { spyOn } from 'tinyspy';
-import { createMockHooks } from "./mock-hooks.js";
+import { createMocksAppPageLocationStore, } from "./mock-app-page-location.js";
 import { createMockExtensionPointApi } from "./mock-extension-point-api.js";
+import { createMockHooks } from "./mock-hooks.js";
 /**
  * This function replaces all methods with a spy using the `spyOn` function from the `tinyspy` library.
  * The object tree is walked recursively to replace all methods with spies. The original object is not modified.
@@ -29,7 +31,7 @@ const spyOnAllFunctionsRecursive = (object) => {
  *
  * @returns An object containing the mocks and spies.
  */
-export const createMocksWithSpies = (extensionPointLocation) => {
+export const createRendererMocksContext = (extensionPointLocation) => {
     const mockExtensionPointApi = createMockExtensionPointApi(extensionPointLocation);
     // Build a mocks object with the default mock functions.
     // NOTE: The mock implementations can be overridden by tests using the spies that are provided in the returned `spies` object.
@@ -37,10 +39,22 @@ export const createMocksWithSpies = (extensionPointLocation) => {
         ...createMockHooks(),
         ...mockExtensionPointApi,
     };
-    // Spy on each of the mocks and build the object with all of the spies.
-    const spies = spyOnAllFunctionsRecursive(mocks);
+    // Recursively create spies for all functions in the mocks object.
+    const mocksWithSpies = spyOnAllFunctionsRecursive(mocks);
+    const appPageLocationStore = createMocksAppPageLocationStore();
     return {
-        mocks,
-        spies: spies,
+        mocks: {
+            // NOTE: These mocks are exposed as part of our public API.
+            ...mocksWithSpies,
+            setPageLocation: (location) => {
+                reactAct(() => {
+                    appPageLocationStore.setPageLocation(location);
+                });
+            },
+        },
+        appPageLocationStore,
+        useAppPageLocation: () => {
+            return useSyncExternalStore(appPageLocationStore.subscribe, appPageLocationStore.getSnapshot);
+        },
     };
 };

package/dist/testing/internal/mocks/mock-app-page-location.d.ts

@@ -0,0 +1,7 @@
+import type { AppPageLocation } from '../../../shared/types/shared.ts';
+export interface MocksAppPageLocationStore {
+    getSnapshot: () => AppPageLocation;
+    setPageLocation: (location: AppPageLocation) => void;
+    subscribe: (listener: () => void) => () => void;
+}
+export declare const createMocksAppPageLocationStore: (initialLocation?: AppPageLocation) => MocksAppPageLocationStore;

package/dist/testing/internal/mocks/mock-app-page-location.js

@@ -0,0 +1,35 @@
+const DEFAULT_PAGE_LOCATION = { path: '/', params: {} };
+const areParamsEqual = (a, b) => {
+    const keysA = Object.keys(a);
+    const keysB = Object.keys(b);
+    if (keysA.length !== keysB.length)
+        return false;
+    for (const key of keysA) {
+        if (a[key] !== b[key])
+            return false;
+    }
+    return true;
+};
+const areAppPageLocationsEqual = (a, b) => a.path === b.path && areParamsEqual(a.params, b.params);
+export const createMocksAppPageLocationStore = (initialLocation = DEFAULT_PAGE_LOCATION) => {
+    let currentLocation = initialLocation;
+    let listeners = [];
+    return {
+        getSnapshot: () => currentLocation,
+        setPageLocation: (location) => {
+            if (areAppPageLocationsEqual(location, currentLocation)) {
+                return;
+            }
+            currentLocation = location;
+            for (const listener of listeners) {
+                listener();
+            }
+        },
+        subscribe: (listener) => {
+            listeners = [...listeners, listener];
+            return () => {
+                listeners = listeners.filter((l) => l !== listener);
+            };
+        },
+    };
+};

package/dist/testing/internal/mocks/mock-extension-point-api.d.ts

@@ -1,2 +1,3 @@
-import { ExtensionPointApi, type ExtensionPointLocation } from '../../../shared/types/extension-points.ts';
+import type { ExtensionPointApi } from '../../../shared/types/extension-points.ts';
+import { type ExtensionPointLocation } from '../../../shared/types/extension-points.ts';
 export declare const createMockExtensionPointApi: (extensionPointLocation: ExtensionPointLocation) => ExtensionPointApi<ExtensionPointLocation>;

package/dist/testing/internal/mocks/mock-extension-point-api.js

@@ -1,4 +1,4 @@
-import { ServerlessExecutionStatus, } from "../../../shared/types/http-requests.js";
+import { ServerlessExecutionStatus } from "../../../shared/types/http-requests.js";
 const fakePrefix = 'fake_';
 const createMockServerlessFuncRunner = () => {
     return () => Promise.resolve({

package/dist/testing/internal/mocks/mock-hooks.d.ts

@@ -1,3 +1,3 @@
-import { RendererMockHooksInternal } from '../types-internal.ts';
 import type { ExtensionPointLocation } from '../../../shared/types/extension-points.ts';
+import type { RendererMockHooksInternal } from '../types-internal.ts';
 export declare const createMockHooks: <TExtensionPointLocation extends ExtensionPointLocation>() => RendererMockHooksInternal;