@hubspot/ui-extensions 0.12.3 → 0.12.4

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

@@ -155,6 +155,12 @@ export interface NumberInputProps extends BaseInputForNumber {
     formatStyle?: 'decimal' | 'percentage';
     /** @deprecated use onChange instead. It doesn't guarantee valid format */
     onInput?: (value: number) => void;
+    /**
+     * Sets the horizontal alignment of the text in the input.
+     *
+     * @defaultValue `"left"`
+     */
+    textAlign?: 'left' | 'right';
 }
 /**
  * The props type for [CurrencyInput](https://developers.hubspot.com/docs/apps/developer-platform/add-features/ui-extensibility/ui-components/standard-components/currency-input).
@@ -185,7 +191,7 @@ export interface CurrencyInputProps extends BaseInputForNumber {
  *
  * @category Component Props
  */
-export interface StepperInputProps extends Omit<NumberInputProps, 'onInput'> {
+export interface StepperInputProps extends Omit<NumberInputProps, 'onInput' | 'textAlign'> {
     /** The amount that the current value will increase or decrease by. Default is `1`.
      * @defaultValue `1`
      */

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

@@ -13,9 +13,9 @@ export interface LinkProps extends OverlayComponentProps, BaseComponentProps {
      */
     children: ReactNode;
     /**
-     * Sets the link's URL and open behavior. Contains the following fields:
+     * Sets the link's URL and open behavior. Can be set to a URL string or an object with the following fields:
      * - `url` (string): the URL that will open on click.
-     * - `external` (boolean): set to `true` to open the URL in a new tab and display an external link icon. By default:
+     * - `external` (boolean, optional): set to `true` to open the URL in a new tab and display an external link icon. By default:
      *   - Links to HubSpot app pages will open in the same tab and will not include an icon.
      *   - Links to non-HubSpot app pages will open in a new tab and include the icon.
      */

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

@@ -1,2 +1,4 @@
+export type * from './page-breadcrumbs.ts';
+export type * from './page-header.ts';
 export type * from './page-link.ts';
-export type * from './page-routes.ts';
+export type * from './page-title.ts';

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

@@ -0,0 +1,34 @@
+import type { ReactNode } from 'react';
+import type { BaseComponentProps } from '../../shared.ts';
+/**
+ * The props type for [PageBreadcrumbs](https://developers.hubspot.com/docs/reference/ui-components/app-page-components/page-breadcrumbs)
+ */
+export interface PageBreadcrumbsProps extends BaseComponentProps {
+    /**
+     * The links and text to render as breadcrumbs.
+     * Use `PageBreadcrumbs.PageLink` for navigable crumbs and `PageBreadcrumbs.Current` for the current page.
+     */
+    children: ReactNode;
+}
+export interface PageBreadcrumbsPageLinkProps 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 text of the breadcrumb link.
+     */
+    children: ReactNode;
+}
+export interface PageBreadcrumbsCurrentProps extends BaseComponentProps {
+    /**
+     * Label for the current location.
+     */
+    children: ReactNode;
+}

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

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

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

@@ -7,7 +7,9 @@ import type { BaseComponentProps } from '../../shared.ts';
  */
 export interface PageLinkProps extends BaseComponentProps {
     /**
-     * The path to navigate to when the link is clicked. Supports path parameters (e.g. `/view-contact/:contactId`).
+     * 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;
     /**
@@ -17,7 +19,7 @@ export interface PageLinkProps extends BaseComponentProps {
      */
     params?: Record<string, string>;
     /**
-     * The content to render inside the link.
+     * The content to display inside the link.
      */
     children: ReactNode;
 }

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/worker-globals.d.ts

@@ -1,8 +1,7 @@
 import type { HubspotExtendFunction } from './extend.ts';
 import type { ExtensionPointApiActions, ExtensionPointApiContext, ExtensionPointFullApi, ExtensionPoints } from './extension-points.ts';
 import type { Logger } from './logger.ts';
-import type { CreatePageRouterFunction, UsePageRouteHook } from './pages/app-pages-types.ts';
-import type { PageRoutesComponent } from './pages/components/page-routes.ts';
+import type { AppPageLocation } from './shared.ts';
 export interface WorkersApi {
     /**
      * Hook added to worker globals so customer code can access extension context at runtime.
@@ -17,17 +16,9 @@ export interface WorkersApi {
      */
     useExtensionApi: <ExtensionPoint extends keyof ExtensionPoints>() => ExtensionPointFullApi<ExtensionPoint>;
     /**
-     * The PageRoutes component.
+     * Hook added to worker globals so page router can access the current app page location at runtime.
      */
-    PageRoutes: PageRoutesComponent;
-    /**
-     * Hook added to worker globals so customer code can access the current page route at runtime.
-     */
-    usePageRoute: UsePageRouteHook;
-    /**
-     * Function added to worker globals so customer code can create a page router at runtime.
-     */
-    createPageRouter: CreatePageRouterFunction;
+    useAppPageLocation: () => AppPageLocation;
 }
 export interface WorkerGlobalsInternal {
     /**

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

@@ -1,12 +1,20 @@
+import { type useAppPageLocation } from '../../../experimental/pages/internal/useAppPageLocation.tsx';
 import type { ExtensionPointLocation } from '../../../shared/types/extension-points.ts';
-import type { RendererSpies } from '../../types.ts';
-import type { RendererMocksInternal } from '../types-internal.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,4 +1,6 @@
+import { act as reactAct, useSyncExternalStore } from 'react';
 import { spyOn } from 'tinyspy';
+import { createMocksAppPageLocationStore, } from "./mock-app-page-location.js";
 import { createMockExtensionPointApi } from "./mock-extension-point-api.js";
 import { createMockHooks } from "./mock-hooks.js";
 /**
@@ -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-hooks.js

@@ -15,6 +15,13 @@ const createFakeProperties = (propertyNames) => {
     }, {});
 };
 export const createMockHooks = () => {
+    const useRequiredMocksContext = () => {
+        const mocksContext = useMocksContext();
+        if (!mocksContext) {
+            throw new Error('Illegal State: Mocks context not found.');
+        }
+        return mocksContext;
+    };
     // 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.
     return {
@@ -61,20 +68,18 @@ export const createMockHooks = () => {
             };
         },
         useExtensionContext: () => {
-            const mocks = useMocksContext();
+            const { mocks } = useRequiredMocksContext();
             return mocks.context;
         },
         useExtensionActions: () => {
-            const mocks = useMocksContext();
-            return mocks
-                .actions;
+            const { mocks } = useRequiredMocksContext();
+            return mocks.actions;
         },
         useExtensionApi: () => {
-            const mocks = useMocksContext();
+            const { mocks } = useRequiredMocksContext();
             return {
                 context: mocks.context,
-                actions: mocks
-                    .actions,
+                actions: mocks.actions,
                 runServerlessFunction: mocks.runServerlessFunction,
             };
         },

package/dist/testing/render.js

@@ -6,7 +6,7 @@ import { EXTENSION_POINT_LOCATIONS } from "../shared/types/extension-points.js";
 import { convertRemoteRoot } from "./internal/convert.js";
 import { createDocument } from "./internal/document.js";
 import { InvalidComponentsError, InvalidExtensionPointLocationError, WaitForTimeoutError, } from "./internal/errors.js";
-import { createMocksWithSpies } from "./internal/mocks/index.js";
+import { createRendererMocksContext, } from "./internal/mocks/index.js";
 import { find, findAll, findAllChildren, findByTestId, findChild, maybeFind, maybeFindByTestId, maybeFindChild, } from "./internal/query.js";
 import { createRootNode } from "./internal/root.js";
 import { asRenderedRootNode } from "./internal/type-utils-internal.js";
@@ -21,7 +21,7 @@ const DEFAULT_WAIT_FOR_OPTIONS = {
  * @param node The React node to render.
  * @returns A render result object
  */
-const render = (node, mocksWithSpies) => {
+const render = (node, mocksContext) => {
     let dirty = true;
     let waitForChecksQueued = false;
     let waitForList = [];
@@ -74,7 +74,7 @@ const render = (node, mocksWithSpies) => {
     };
     const remoteRoot = createRemoteRoot(remoteChannel);
     const reactRoot = createReactRoot(remoteRoot);
-    reactRoot.render(_jsx(MocksContextProvider, { value: mocksWithSpies, children: node }));
+    reactRoot.render(_jsx(MocksContextProvider, { value: mocksContext, children: node }));
     remoteRoot.mount();
     let maybeRenderedRootNode;
     /**
@@ -174,13 +174,14 @@ export const createRenderer = (extensionPointLocation) => {
         return renderResult;
     };
     const getLatestRootNode = () => getRenderResult().getLatestRootNode();
-    const { spies: mocksWithSpies } = createMocksWithSpies(extensionPointLocation);
+    const mocksContext = createRendererMocksContext(extensionPointLocation);
+    const { mocks } = mocksContext;
     return {
         render: (node) => {
-            renderResult = render(node, mocksWithSpies);
+            renderResult = render(node, mocksContext);
             return asRenderedRootNode(renderResult.getLatestRootNode());
         },
-        mocks: mocksWithSpies,
+        mocks: mocks,
         find: (component, matcher) => {
             return find(getLatestRootNode(), component, matcher);
         },

package/dist/testing/types.d.ts

@@ -1,11 +1,12 @@
 import type { SpyImpl } from 'tinyspy';
 import type { useAssociations, useCrmProperties } from '../crm/index.ts';
+import type { useAppPageLocation } from '../experimental/pages/internal/useAppPageLocation.tsx';
 import type { useExtensionActions } from '../hooks/useExtensionActions.tsx';
 import type { useExtensionApi } from '../hooks/useExtensionApi.tsx';
 import type { useExtensionContext } from '../hooks/useExtensionContext.tsx';
 import type { ExtensionPointApi, ExtensionPointApiActions, ExtensionPointLocation } from '../shared/types/extension-points.ts';
 import type { ServerlessFuncRunner } from '../shared/types/http-requests.ts';
-import type { HubSpotReactComponent, HubSpotReactFragmentProp, UnknownComponentProps } from '../shared/types/shared.ts';
+import type { AppPageLocation, HubSpotReactComponent, HubSpotReactFragmentProp, UnknownComponentProps } from '../shared/types/shared.ts';
 import type { AnyFunction } from './internal/types-internal.ts';
 /**
  * The type of a rendered node.
@@ -261,7 +262,7 @@ export type ExtensionPointApiActionSpies<TExtensionPointLocation extends Extensi
 /**
  * An object containing the spies for the various functions.
  */
-export interface RendererSpies<TExtensionPointLocation extends ExtensionPointLocation = ExtensionPointLocation> {
+export interface RendererMocks<TExtensionPointLocation extends ExtensionPointLocation = ExtensionPointLocation> {
     /**
      * A spy for the `useCrmProperties` hook function.
      * The spy can be used to track the calls to the hook function and also control the
@@ -307,6 +308,15 @@ export interface RendererSpies<TExtensionPointLocation extends ExtensionPointLoc
      * information about spies and the supported API.
      */
     useExtensionApi: FunctionSpy<typeof useExtensionApi>;
+    /**
+     * A spy for the `useAppPageLocation` hook function.
+     * The spy can be used to track the calls to the hook function and also control the
+     * return result of the hook function.
+     *
+     * See the [tinyspy](https://github.com/tiny-spy/tinyspy) library for more
+     * information about spies and the supported API.
+     */
+    useAppPageLocation: FunctionSpy<typeof useAppPageLocation>;
     /**
      * Mock context object that contains fake context data for the extension point API.
      */
@@ -329,6 +339,12 @@ export interface RendererSpies<TExtensionPointLocation extends ExtensionPointLoc
      * information about spies and the supported API.
      */
     runServerlessFunction: FunctionSpy<ServerlessFuncRunner>;
+    /**
+     * Sets the current app page location for testing page routing.
+     *
+     * @param location The app page location to set.
+     */
+    setPageLocation: (location: AppPageLocation) => void;
 }
 /**
  * A result of a render operation.
@@ -363,7 +379,7 @@ export interface Renderer<TExtensionPointLocation extends ExtensionPointLocation
     /**
      * The mocks that can be used to control the behavior of the various functions.
      */
-    mocks: RendererSpies<TExtensionPointLocation>;
+    mocks: RendererMocks<TExtensionPointLocation>;
     /**
      * Finds the first descendant element node that matches the given component and test ID.
      *

package/dist/utils/pagination.d.ts

@@ -0,0 +1,17 @@
+export interface PaginationResult {
+    hasNextPage: boolean;
+    hasPreviousPage: boolean;
+    currentPage: number;
+    pageSize: number;
+    nextPage: () => void;
+    previousPage: () => void;
+    reset: () => void;
+}
+export declare const DEFAULT_PAGE_SIZE = 10;
+/**
+ * Calculate pagination flags based on current page and API hasMore flag
+ */
+export declare function calculatePaginationFlags(currentPage: number, hasMore: boolean): {
+    hasNextPage: boolean;
+    hasPreviousPage: boolean;
+};

package/dist/utils/pagination.js

@@ -0,0 +1,10 @@
+export const DEFAULT_PAGE_SIZE = 10;
+/**
+ * Calculate pagination flags based on current page and API hasMore flag
+ */
+export function calculatePaginationFlags(currentPage, hasMore) {
+    return {
+        hasNextPage: hasMore,
+        hasPreviousPage: currentPage > 1,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hubspot/ui-extensions",
-  "version": "0.12.3",
+  "version": "0.12.4",
   "description": "",
   "type": "module",
   "main": "dist/index.js",