@hubspot/ui-extensions 0.11.6 → 0.12.1

package/dist/hooks/useExtensionActions.d.ts

@@ -1,4 +1,20 @@
 import type { ExtensionPoints } from '../shared/types/extension-points.ts';
-declare function useExtensionActionsInternal<ExtensionPoint extends keyof ExtensionPoints>(): import("../shared/types/extension-points.ts").ExtensionPointApiActions<ExtensionPoint>;
+declare function useExtensionActionsInternal<TExtensionPoint extends keyof ExtensionPoints>(): import("../shared/types/extension-points.ts").ExtensionPointApiActions<TExtensionPoint>;
+/**
+ * Hook that provides access to extension actions for the specified extension point.
+ *
+ * Actions are methods provided by the host application that extensions can invoke to
+ * interact with the platform, such as showing notifications, opening modals, or
+ * navigating to different views.
+ *
+ * @typeParam TExtensionPoint - The extension point location (e.g., 'crm.record.tab', 'settings')
+ * @returns The actions object containing all available action methods for the extension point
+ *
+ * @example
+ * ```tsx
+ * const actions = useExtensionActions<'crm.record.tab'>();
+ * // Use actions like: actions.openIframeModal(...)
+ * ```
+ */
 export declare const useExtensionActions: typeof useExtensionActionsInternal;
 export {};

package/dist/hooks/useExtensionActions.js

@@ -3,4 +3,20 @@ import { createMockAwareHook } from "../internal/hook-utils.js";
 function useExtensionActionsInternal() {
     return getWorkerGlobals().hsWorkerAPI.useExtensionActions();
 }
+/**
+ * Hook that provides access to extension actions for the specified extension point.
+ *
+ * Actions are methods provided by the host application that extensions can invoke to
+ * interact with the platform, such as showing notifications, opening modals, or
+ * navigating to different views.
+ *
+ * @typeParam TExtensionPoint - The extension point location (e.g., 'crm.record.tab', 'settings')
+ * @returns The actions object containing all available action methods for the extension point
+ *
+ * @example
+ * ```tsx
+ * const actions = useExtensionActions<'crm.record.tab'>();
+ * // Use actions like: actions.openIframeModal(...)
+ * ```
+ */
 export const useExtensionActions = createMockAwareHook('useExtensionActions', useExtensionActionsInternal);

package/dist/hooks/useExtensionApi.d.ts

@@ -0,0 +1,20 @@
+import type { ExtensionPoints } from '../shared/types/extension-points.ts';
+declare function useExtensionApiInternal<TExtensionPoint extends keyof ExtensionPoints>(): import("../shared/types/extension-points.ts").ExtensionPointFullApi<TExtensionPoint>;
+/**
+ * Hook that provides access to the full extension API for the specified extension point.
+ *
+ * The extension API includes:
+ * - `actions`: Methods to interact with the host application
+ * - `context`: Contextual data about the current environment
+ * - `runServerlessFunction`: Function to execute serverless functions (deprecated)
+ *
+ * @typeParam TExtensionPoint - The extension point location (e.g., 'crm.record.tab', 'settings')
+ * @returns The complete extension API object containing actions, context, and runServerlessFunction
+ *
+ * @example
+ * ```tsx
+ * const { actions, context, runServerlessFunction } = useExtensionApi<'crm.record.tab'>();
+ * ```
+ */
+export declare const useExtensionApi: typeof useExtensionApiInternal;
+export {};

package/dist/hooks/useExtensionApi.js

@@ -0,0 +1,22 @@
+import { getWorkerGlobals } from "../internal/global-utils.js";
+import { createMockAwareHook } from "../internal/hook-utils.js";
+function useExtensionApiInternal() {
+    return getWorkerGlobals().hsWorkerAPI.useExtensionApi();
+}
+/**
+ * Hook that provides access to the full extension API for the specified extension point.
+ *
+ * The extension API includes:
+ * - `actions`: Methods to interact with the host application
+ * - `context`: Contextual data about the current environment
+ * - `runServerlessFunction`: Function to execute serverless functions (deprecated)
+ *
+ * @typeParam TExtensionPoint - The extension point location (e.g., 'crm.record.tab', 'settings')
+ * @returns The complete extension API object containing actions, context, and runServerlessFunction
+ *
+ * @example
+ * ```tsx
+ * const { actions, context, runServerlessFunction } = useExtensionApi<'crm.record.tab'>();
+ * ```
+ */
+export const useExtensionApi = createMockAwareHook('useExtensionApi', useExtensionApiInternal);

package/dist/hooks/useExtensionContext.d.ts

@@ -1,4 +1,20 @@
 import type { ExtensionPoints } from '../shared/types/extension-points.ts';
-declare function useExtensionContextInternal<ExtensionPoint extends keyof ExtensionPoints>(): import("../shared/types/extension-points.ts").ExtensionPointApiContext<ExtensionPoint>;
+declare function useExtensionContextInternal<TExtensionPoint extends keyof ExtensionPoints>(): import("../shared/types/extension-points.ts").ExtensionPointApiContext<TExtensionPoint>;
+/**
+ * Hook that provides access to contextual data for the specified extension point.
+ *
+ * The context contains information about the current environment where the extension
+ * is running, such as the current CRM object, user information, portal settings,
+ * and other relevant data specific to the extension point location.
+ *
+ * @typeParam TExtensionPoint - The extension point location (e.g., 'crm.record.tab', 'settings')
+ * @returns The context object containing environment-specific data for the extension point
+ *
+ * @example
+ * ```tsx
+ * const context = useExtensionContext<'crm.record.tab'>();
+ * // Access properties like: context.crm.objectId, context.user, context.portal
+ * ```
+ */
 export declare const useExtensionContext: typeof useExtensionContextInternal;
 export {};

package/dist/hooks/useExtensionContext.js

@@ -3,4 +3,20 @@ import { createMockAwareHook } from "../internal/hook-utils.js";
 function useExtensionContextInternal() {
     return getWorkerGlobals().hsWorkerAPI.useExtensionContext();
 }
+/**
+ * Hook that provides access to contextual data for the specified extension point.
+ *
+ * The context contains information about the current environment where the extension
+ * is running, such as the current CRM object, user information, portal settings,
+ * and other relevant data specific to the extension point location.
+ *
+ * @typeParam TExtensionPoint - The extension point location (e.g., 'crm.record.tab', 'settings')
+ * @returns The context object containing environment-specific data for the extension point
+ *
+ * @example
+ * ```tsx
+ * const context = useExtensionContext<'crm.record.tab'>();
+ * // Access properties like: context.crm.objectId, context.user, context.portal
+ * ```
+ */
 export const useExtensionContext = createMockAwareHook('useExtensionContext', useExtensionContextInternal);

package/dist/hs-internal/__tests__/createRemoteComponentInternal.spec.d.ts

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

package/dist/hs-internal/__tests__/createRemoteComponentInternal.spec.js

@@ -0,0 +1,139 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { describe, expect, it } from 'vitest';
+import { createRenderer } from "../../testing/index.js";
+import { createRemoteComponentInternal } from "../index.js";
+import { __hubSpotComponentRegistry } from "../../shared/remoteComponents.js";
+import { Button, Text } from "../../index.js";
+import { InvalidComponentsError } from "../../testing/internal/errors.js";
+import { useState } from 'react';
+// Create custom components once at the top level
+const CustomButton = createRemoteComponentInternal('TestCustomButton');
+const CustomCard = createRemoteComponentInternal('TestCustomCard', {
+    fragmentProps: ['content'],
+});
+describe('createRemoteComponentInternal', () => {
+    it('should create a component that can be rendered', () => {
+        const { render, find } = createRenderer('crm.record.tab');
+        render(_jsx(CustomButton, { label: "Click me", onClick: () => { }, testId: "my-button" }));
+        const button = find(CustomButton);
+        expect(button.props.label).toBe('Click me');
+        expect(button.props.testId).toBe('my-button');
+    });
+    it('should register component in the registry', () => {
+        expect(__hubSpotComponentRegistry.isAllowedComponentName('TestCustomButton')).toBe(true);
+    });
+    it('should be findable using renderer.find()', () => {
+        const { render, find } = createRenderer('crm.record.tab');
+        render(_jsx(CustomButton, { label: "Find me", onClick: () => { } }));
+        const button = find(CustomButton);
+        expect(button).toBeDefined();
+        expect(button.props.label).toBe('Find me');
+    });
+    it('should work with find() using prop matchers', () => {
+        const { render, find } = createRenderer('crm.record.tab');
+        render(_jsxs(_Fragment, { children: [_jsx(CustomButton, { label: "Button 1", onClick: () => { }, variant: "primary" }), _jsx(CustomButton, { label: "Button 2", onClick: () => { }, variant: "secondary" })] }));
+        const primaryButton = find(CustomButton, { variant: 'primary' });
+        expect(primaryButton.props.label).toBe('Button 1');
+        const secondaryButton = find(CustomButton, { variant: 'secondary' });
+        expect(secondaryButton.props.label).toBe('Button 2');
+    });
+    it('should work with findAll()', () => {
+        const { render, findAll } = createRenderer('crm.record.tab');
+        render(_jsxs(_Fragment, { children: [_jsx(CustomButton, { label: "Button 1", onClick: () => { } }), _jsx(CustomButton, { label: "Button 2", onClick: () => { } }), _jsx(CustomButton, { label: "Button 3", onClick: () => { } })] }));
+        const buttons = findAll(CustomButton);
+        expect(buttons).toHaveLength(3);
+        expect(buttons[0].props.label).toBe('Button 1');
+        expect(buttons[1].props.label).toBe('Button 2');
+        expect(buttons[2].props.label).toBe('Button 3');
+    });
+    it('should work with findByTestId()', () => {
+        const { render, findByTestId } = createRenderer('crm.record.tab');
+        render(_jsx(CustomButton, { label: "Find by ID", onClick: () => { }, testId: "my-custom-button" }));
+        const button = findByTestId(CustomButton, 'my-custom-button');
+        expect(button.props.label).toBe('Find by ID');
+    });
+    it('should work with maybeFind()', () => {
+        const { render, maybeFind } = createRenderer('crm.record.tab');
+        render(_jsx(CustomButton, { label: "Maybe", onClick: () => { } }));
+        const button = maybeFind(CustomButton);
+        expect(button).not.toBeNull();
+        expect(button?.props.label).toBe('Maybe');
+        const nonExistent = maybeFind(Button);
+        expect(nonExistent).toBeNull();
+    });
+    it('should support fragment props', () => {
+        const { render, find } = createRenderer('crm.record.tab');
+        render(_jsx(CustomCard, { title: "My Card", content: _jsx(Text, { children: "Card content" }), testId: "my-card" }));
+        const card = find(CustomCard);
+        expect(card.props.title).toBe('My Card');
+        expect(card.props.testId).toBe('my-card');
+        expect(card.props.content?.find(Text).text).toBe('Card content');
+    });
+    it('should support event triggering via trigger()', () => {
+        const { render, find } = createRenderer('crm.record.tab');
+        let clicked = false;
+        const handleClick = () => {
+            clicked = true;
+        };
+        render(_jsx(CustomButton, { label: "Click me", onClick: handleClick }));
+        const button = find(CustomButton);
+        button.trigger('onClick');
+        expect(clicked).toBe(true);
+    });
+    it('should not throw InvalidComponentsError during rendering', () => {
+        const { render } = createRenderer('crm.record.tab');
+        expect(() => render(_jsx(CustomButton, { label: "Valid", onClick: () => { } }))).not.toThrow(InvalidComponentsError);
+    });
+    it('should work with state updates', () => {
+        const { render, find } = createRenderer('crm.record.tab');
+        function Counter() {
+            const [count, setCount] = useState(0);
+            const handleClick = () => {
+                setCount(count + 1);
+            };
+            return (_jsx(CustomButton, { label: `Count: ${count}`, onClick: handleClick, testId: "counter" }));
+        }
+        render(_jsx(Counter, {}));
+        const button = find(CustomButton);
+        expect(button.props.label).toBe('Count: 0');
+        button.trigger('onClick');
+        const updatedButton = find(CustomButton);
+        expect(updatedButton.props.label).toBe('Count: 1');
+    });
+    it('should work with nested components', () => {
+        const { render, find } = createRenderer('crm.record.tab');
+        render(_jsx(CustomCard, { title: "Card with button", content: _jsx(CustomButton, { label: "Nested button", onClick: () => { } }) }));
+        const card = find(CustomCard);
+        expect(card.props.title).toBe('Card with button');
+        // Fragment prop children are found globally, not as direct children
+        const nestedButton = find(CustomButton);
+        expect(nestedButton.props.label).toBe('Nested button');
+    });
+    it('should work with findChild() and findAllChildren()', () => {
+        const { render, findAll, find } = createRenderer('crm.record.tab');
+        render(_jsx(CustomCard, { title: "Card with buttons", content: _jsxs(_Fragment, { children: [_jsx(CustomButton, { label: "Button 1", onClick: () => { } }), _jsx(CustomButton, { label: "Button 2", onClick: () => { } })] }) }));
+        const card = find(CustomCard);
+        expect(card.props.title).toBe('Card with buttons');
+        // Fragment prop children are found globally, not as direct children
+        const buttons = findAll(CustomButton);
+        expect(buttons).toHaveLength(2);
+        expect(buttons[0].props.label).toBe('Button 1');
+        expect(buttons[1].props.label).toBe('Button 2');
+    });
+    it('should allow multiple custom components to coexist', () => {
+        const { render, find } = createRenderer('crm.record.tab');
+        render(_jsxs(_Fragment, { children: [_jsx(CustomButton, { label: "Button", onClick: () => { } }), _jsx(CustomCard, { title: "Card" })] }));
+        const button = find(CustomButton);
+        const card = find(CustomCard);
+        expect(button.props.label).toBe('Button');
+        expect(card.props.title).toBe('Card');
+    });
+    it('should work alongside built-in HubSpot components', () => {
+        const { render, find } = createRenderer('crm.record.tab');
+        render(_jsxs(_Fragment, { children: [_jsx(CustomButton, { label: "Custom", onClick: () => { } }), _jsx(Button, { variant: "primary", children: "Built-in" })] }));
+        const customButton = find(CustomButton);
+        const builtInButton = find(Button);
+        expect(customButton.props.label).toBe('Custom');
+        expect(builtInButton.props.variant).toBe('primary');
+    });
+});

package/dist/hs-internal/index.d.ts

@@ -0,0 +1,35 @@
+import type { HubSpotReactComponent, HubSpotReactFragmentProp, UnknownComponentProps } from '../shared/types/shared.ts';
+/**
+ * Utility type for filtering out all of the prop names where the value is a ReactNode.
+ * We use this to know which props are allowed to be used as fragment props.
+ */
+type ComponentFragmentPropName<TProps extends UnknownComponentProps> = {
+    [K in keyof TProps]: HubSpotReactFragmentProp extends Required<TProps>[K] ? K : never;
+}[keyof TProps & string];
+/**
+ * Options for creating a custom remote component.
+ */
+export interface CreateRemoteComponentInternalOptions<TProps extends UnknownComponentProps = UnknownComponentProps> {
+    /**
+     * An array of prop names that are allowed to be used as fragment props (props that accept ReactNode children).
+     */
+    fragmentProps?: ComponentFragmentPropName<TProps>[];
+}
+/**
+ * Creates and registers a custom remote component for internal HubSpot use.
+ *
+ * This function is intended for HubSpot internal teams who need to create
+ * custom remote components that work with the UI Extensions testing utilities.
+ *
+ * Components created with this function will:
+ * - Be registered in the global component registry
+ * - Pass validation in testing utilities (isAllowedComponentName)
+ * - Work with renderer.find(), renderer.findAll(), and other testing utilities
+ *
+ * @param componentName - Unique name for the component (e.g., "FlywheelCustomButton").
+ *                        Recommended to prefix with team name to avoid collisions.
+ * @param options - Optional configuration including fragment props
+ * @returns A typed remote React component that can be rendered in a remote environment
+ */
+export declare function createRemoteComponentInternal<TProps extends UnknownComponentProps>(componentName: string, options?: CreateRemoteComponentInternalOptions<TProps>): HubSpotReactComponent<TProps>;
+export {};

package/dist/hs-internal/index.js

@@ -0,0 +1,20 @@
+import { __hubSpotComponentRegistry } from "../shared/remoteComponents.js";
+/**
+ * Creates and registers a custom remote component for internal HubSpot use.
+ *
+ * This function is intended for HubSpot internal teams who need to create
+ * custom remote components that work with the UI Extensions testing utilities.
+ *
+ * Components created with this function will:
+ * - Be registered in the global component registry
+ * - Pass validation in testing utilities (isAllowedComponentName)
+ * - Work with renderer.find(), renderer.findAll(), and other testing utilities
+ *
+ * @param componentName - Unique name for the component (e.g., "FlywheelCustomButton").
+ *                        Recommended to prefix with team name to avoid collisions.
+ * @param options - Optional configuration including fragment props
+ * @returns A typed remote React component that can be rendered in a remote environment
+ */
+export function createRemoteComponentInternal(componentName, options = {}) {
+    return __hubSpotComponentRegistry.createAndRegisterRemoteReactComponent(componentName, options);
+}

package/dist/index.d.ts

@@ -2,6 +2,7 @@ import './clientTypes.ts';
 export { hubspot } from './hubspot.ts';
 export { logger } from './logger.ts';
 export * from './shared/types/index.ts';
-export { Accordion, Alert, AutoGrid, BarChart, Box, Button, ButtonRow, Card, Checkbox, CurrencyInput, DateInput, DescriptionList, DescriptionListItem, Divider, Dropdown, EmptyState, ErrorState, Flex, Form, Heading, Icon, Illustration, Image, Inline, Input, LineChart, Link, List, LoadingButton, LoadingSpinner, Modal, ModalBody, ModalFooter, MultiSelect, NumberInput, Panel, PanelBody, PanelFooter, PanelSection, ProgressBar, RadioButton, SearchInput, Select, Stack, Statistics, StatisticsItem, StatisticsTrend, StatusTag, StepIndicator, StepperInput, Tab, Table, TableBody, TableCell, TableFooter, TableHead, TableHeader, TableRow, Tabs, Tag, Text, TextArea, Textarea, Tile, TimeInput, Toggle, ToggleGroup, Tooltip, } from './shared/remoteComponents.tsx';
+export { Accordion, Alert, AutoGrid, BarChart, Box, Button, ButtonRow, Card, Checkbox, CurrencyInput, DateInput, DescriptionList, DescriptionListItem, Divider, Dropdown, EmptyState, ErrorState, Flex, Form, Heading, Icon, Illustration, Image, Inline, Input, LineChart, Link, List, LoadingButton, LoadingSpinner, Modal, ModalBody, ModalFooter, MultiSelect, NumberInput, Panel, PanelBody, PanelFooter, PanelSection, ProgressBar, RadioButton, ScoreCircle, SearchInput, Select, Stack, Statistics, StatisticsItem, StatisticsTrend, StatusTag, StepIndicator, StepperInput, Tab, Table, TableBody, TableCell, TableFooter, TableHead, TableHeader, TableRow, Tabs, Tag, Text, TextArea, Textarea, Tile, TimeInput, Toggle, ToggleGroup, Tooltip, } from './shared/remoteComponents.tsx';
 export { useExtensionContext } from './hooks/useExtensionContext.tsx';
 export { useExtensionActions } from './hooks/useExtensionActions.tsx';
+export { useExtensionApi } from './hooks/useExtensionApi.tsx';

package/dist/index.js

@@ -3,6 +3,7 @@ import "./clientTypes.js";
 export { hubspot } from "./hubspot.js";
 export { logger } from "./logger.js";
 export * from "./shared/types/index.js";
-export { Accordion, Alert, AutoGrid, BarChart, Box, Button, ButtonRow, Card, Checkbox, CurrencyInput, DateInput, DescriptionList, DescriptionListItem, Divider, Dropdown, EmptyState, ErrorState, Flex, Form, Heading, Icon, Illustration, Image, Inline, Input, LineChart, Link, List, LoadingButton, LoadingSpinner, Modal, ModalBody, ModalFooter, MultiSelect, NumberInput, Panel, PanelBody, PanelFooter, PanelSection, ProgressBar, RadioButton, SearchInput, Select, Stack, Statistics, StatisticsItem, StatisticsTrend, StatusTag, StepIndicator, StepperInput, Tab, Table, TableBody, TableCell, TableFooter, TableHead, TableHeader, TableRow, Tabs, Tag, Text, TextArea, Textarea, Tile, TimeInput, Toggle, ToggleGroup, Tooltip, } from "./shared/remoteComponents.js";
+export { Accordion, Alert, AutoGrid, BarChart, Box, Button, ButtonRow, Card, Checkbox, CurrencyInput, DateInput, DescriptionList, DescriptionListItem, Divider, Dropdown, EmptyState, ErrorState, Flex, Form, Heading, Icon, Illustration, Image, Inline, Input, LineChart, Link, List, LoadingButton, LoadingSpinner, Modal, ModalBody, ModalFooter, MultiSelect, NumberInput, Panel, PanelBody, PanelFooter, PanelSection, ProgressBar, RadioButton, ScoreCircle, SearchInput, Select, Stack, Statistics, StatisticsItem, StatisticsTrend, StatusTag, StepIndicator, StepperInput, Tab, Table, TableBody, TableCell, TableFooter, TableHead, TableHeader, TableRow, Tabs, Tag, Text, TextArea, Textarea, Tile, TimeInput, Toggle, ToggleGroup, Tooltip, } from "./shared/remoteComponents.js";
 export { useExtensionContext } from "./hooks/useExtensionContext.js";
 export { useExtensionActions } from "./hooks/useExtensionActions.js";
+export { useExtensionApi } from "./hooks/useExtensionApi.js";

package/dist/shared/remoteComponents.d.ts

@@ -483,7 +483,7 @@ export declare const LoadingButton: import("./types/shared.ts").HubSpotReactComp
  * - {@link https://developers.hubspot.com/docs/reference/ui-components/standard-components/charts Charts Docs}
  * - {@link https://github.com/HubSpot/ui-extensions-examples/tree/main/charts-example Charts Example}
  */
-export declare const BarChart: import("./types/shared.ts").HubSpotReactComponent<componentTypes.ChartProps>;
+export declare const BarChart: import("./types/shared.ts").HubSpotReactComponent<componentTypes.BarChartProps>;
 /**
  * The `LineChart` component renders a line chart for visualizing data. This type of chart is best suited for time series plots or trend data.
  *
@@ -493,7 +493,16 @@ export declare const BarChart: import("./types/shared.ts").HubSpotReactComponent
  * - {@link https://developers.hubspot.com/docs/reference/ui-components/standard-components/charts Charts Docs}
  * - {@link https://github.com/HubSpot/ui-extensions-examples/tree/main/charts-example Charts Example}
  */
-export declare const LineChart: import("./types/shared.ts").HubSpotReactComponent<componentTypes.ChartProps>;
+export declare const LineChart: import("./types/shared.ts").HubSpotReactComponent<componentTypes.LineChartProps>;
+/**
+ * The `ScoreCircle` component displays a score value (0-100) as a circular progress indicator with color-coded bands.
+ * Scores are color-coded: 0-32 (alert/red), 33-65 (warning/yellow), 66-100 (success/green).
+ * @example
+ * ```tsx
+ *   <ScoreCircle score={75} />
+ * ```
+ */
+export declare const ScoreCircle: import("./types/shared.ts").HubSpotReactComponent<componentTypes.ScoreProps>;
 /**
  * `Tabs` allow you to group related content in a compact space, allowing users to switch between views without leaving the page.
  * @example

package/dist/shared/remoteComponents.js

@@ -504,6 +504,15 @@ export const BarChart = createAndRegisterRemoteReactComponent('BarChart');
  * - {@link https://github.com/HubSpot/ui-extensions-examples/tree/main/charts-example Charts Example}
  */
 export const LineChart = createAndRegisterRemoteReactComponent('LineChart');
+/**
+ * The `ScoreCircle` component displays a score value (0-100) as a circular progress indicator with color-coded bands.
+ * Scores are color-coded: 0-32 (alert/red), 33-65 (warning/yellow), 66-100 (success/green).
+ * @example
+ * ```tsx
+ *   <ScoreCircle score={75} />
+ * ```
+ */
+export const ScoreCircle = createAndRegisterRemoteReactComponent('ScoreCircle');
 /**
  * `Tabs` allow you to group related content in a compact space, allowing users to switch between views without leaving the page.
  * @example

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

@@ -1,32 +1,93 @@
 import { BaseComponentProps } from '../shared.ts';
+export interface ChartProps extends BaseComponentProps {
+    /**
+     * An object containing the chart's data in an array.
+     */
+    data: ChartDataRow[] | {
+        data: ChartDataRow[];
+        options?: ChartDataOptions;
+    };
+    /**
+     * Configures the chart's axes.
+     */
+    axes: ChartAxisPair;
+    /**
+     * Additional chart configuration options. Options include:
+     * - `title` (string): a title for the chart.
+     * - `showLegend` (boolean): set to `true` to display a legend above the chart.
+     * - `showDataLabels` (boolean): set to `true` to display labels above data points.
+     * - `showTooltips` (boolean): set to `true` to display tooltips for data points on hover.
+     * - `colorList` (array): specify a custom order for colors to be used in the report.
+     *
+     * Learn more about [chart options](https://developers.hubspot.com/docs/apps/developer-platform/add-features/ui-extensibility/ui-components/standard-components/charts/overview#chart-options).
+     */
+    options?: ChartOptions;
+}
 /**
  * The props type for {@link !components.BarChart}.
  *
  * @category Component Props
  */
-export type BarChartProps = ChartProps;
+export interface BarChartProps extends ChartProps {
+    /**
+     * An object containing the chart's data in an array.
+     * - Data should be formatted as comma-separated objects containing key-value pairs.
+     * - Data will be displayed in the order it's provided, so any sorting will need to be done before passing it to the component.
+     * - While it's recommended to pre-format your data to be human-readable, you can also provide the `propertyLabels` parameter via this prop's `options` to relabel data values. See example in the [Stacking section](https://developers.hubspot.com/docs/apps/developer-platform/add-features/ui-extensibility/ui-components/standard-components/charts/bar-chart#stacking).
+     *
+     * Learn more about [formatting data](https://developers.hubspot.com/docs/apps/developer-platform/add-features/ui-extensibility/ui-components/standard-components/charts/overview#formatting-data).
+     */
+    data: ChartDataRow[] | {
+        data: ChartDataRow[];
+        options?: ChartDataOptions;
+    };
+    /**
+     * Configures the chart's axes. Using the `x` and `y` fields, you'll configure each axis individually with `field` and `fieldType` parameters, along with an optional `label` parameter:
+     * - `field` (Required): the field from your dataset to use. This value will be used as the displayed axis label if no `label` is specified.
+     * - `fieldType` (Required): the type of field. Can be `category`, `datetime`, or `linear`. Learn more about [field types](https://developers.hubspot.com/docs/apps/developer-platform/add-features/ui-extensibility/ui-components/standard-components/charts/overview#configuring-axes).
+     * - `label`: the axis label. If not specified, the `field` value will be used.
+     *
+     * You can also include an `options` field to further configure the axes with the following options:
+     * - `groupFieldByColor` (string): specify a field to [apply color](https://developers.hubspot.com/docs/apps/developer-platform/add-features/ui-extensibility/ui-components/standard-components/charts/bar-chart#colors) to for visual clarity.
+     * - `stacking` (boolean): [stack grouped data](https://developers.hubspot.com/docs/apps/developer-platform/add-features/ui-extensibility/ui-components/standard-components/charts/bar-chart#stacking) instead of always rendering separate bars.
+     * - `colors` (object): [specify colors for values](https://developers.hubspot.com/docs/apps/developer-platform/add-features/ui-extensibility/ui-components/standard-components/charts/bar-chart#specify-colors-per-field-value) in the field specified in `groupFieldByColor`.
+     *
+     * Learn more about [chart axes](https://developers.hubspot.com/docs/apps/developer-platform/add-features/ui-extensibility/ui-components/standard-components/charts/overview#configuring-axes).
+     */
+    axes: ChartAxisPair;
+}
 /**
  * The props type for {@link !components.LineChart}.
  *
  * @category Component Props
  */
-export type LineChartProps = ChartProps;
-export interface ChartProps extends BaseComponentProps {
+export interface LineChartProps extends ChartProps {
     /**
      * An object containing the chart's data in an array.
+     * - Data should be formatted as comma-separated objects containing key-value pairs.
+     * - Data will be displayed in the order it's provided, so any sorting will need to be done before passing it to the component.
+     * - While it's recommended to pre-format your data to be human-readable, you can also provide the `propertyLabels` parameter via this prop's `options` to relabel data values. See example in the [Stacking section](https://developers.hubspot.com/docs/apps/developer-platform/add-features/ui-extensibility/ui-components/standard-components/charts/line-chart#stacking).
+     *
+     * Learn more about [formatting data](https://developers.hubspot.com/docs/apps/developer-platform/add-features/ui-extensibility/ui-components/standard-components/charts/overview#formatting-data).
      */
     data: ChartDataRow[] | {
         data: ChartDataRow[];
         options?: ChartDataOptions;
     };
     /**
-     * Configures the chart's axes.
+     * Configures the chart's axes. Using the `x` and `y` fields, you'll configure each axis individually with `field` and `fieldType` parameters, along with an optional `label` parameter:
+     * - `field` (Required): the field from your dataset to use. This value will be used as the displayed axis label if no `label` is specified.
+     * - `fieldType` (Required): the type of field. Can be `category`, `datetime`, or `linear`. Learn more about [field types](https://developers.hubspot.com/docs/apps/developer-platform/add-features/ui-extensibility/ui-components/standard-components/charts/overview#configuring-axes).
+     * - `label`: the axis label. If not specified, the `field` value will be used.
+     *
+     * You can also include an `options` field to further configure the axes with the following options:
+     * - `groupFieldByColor` (string): specify a field to [apply color](https://developers.hubspot.com/docs/apps/developer-platform/add-features/ui-extensibility/ui-components/standard-components/charts/line-chart#colors) to for visual clarity.
+     * - `stacking` (boolean): [stack grouped data](https://developers.hubspot.com/docs/apps/developer-platform/add-features/ui-extensibility/ui-components/standard-components/charts/line-chart#stacking) instead of always rendering separated lines.
+     * - `colors` (object): [specify colors for values](https://developers.hubspot.com/docs/apps/developer-platform/add-features/ui-extensibility/ui-components/standard-components/charts/line-chart#specify-colors-per-field-value) in the field specified in `groupFieldByColor`.
+     *
+     * Learn more about [chart axes](https://developers.hubspot.com/docs/apps/developer-platform/add-features/ui-extensibility/ui-components/standard-components/charts/overview#configuring-axes).
      */
     axes: ChartAxisPair;
-    /**
-     * Additional chart configuration options.
-     */
-    options?: ChartOptions;
 }
 export type ChartDataRow = {
     [key: string]: number | string;

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

@@ -24,6 +24,7 @@ export type * from './loading-spinner.ts';
 export type * from './modal.ts';
 export type * from './panel.ts';
 export type * from './progress-bar.ts';
+export type * from './score.ts';
 export type * from './selects.ts';
 export type * from './statistics.ts';
 export type * from './status-tag.ts';

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

@@ -272,6 +272,17 @@ export interface DateInputProps extends BaseDateInputForDate {
      * @defaultValue `'userTz'`
      */
     timezone?: 'userTz' | 'portalTz';
+    /**
+     * The value of the input. Must include the year, month, and day.
+     * - `year`: the four-digit year (e.g., `2023`).
+     * - `month`: starting at `0`, the number of the month (e.g., `0` = January, `11` = December).
+     * - `date`: the number of the day (e.g., `1` = the first day of the month).
+     */
+    value?: BaseDate;
+    /**
+     * The default date value. Uses the same format as the value field.
+     */
+    defaultValue?: BaseDate;
 }
 /**
  * Object that represents times.

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

@@ -0,0 +1,13 @@
+import { BaseComponentProps } from '../shared.ts';
+/**
+ * The props type for {@link !components.ScoreCircle}.
+ *
+ * @category Component Props
+ */
+export type ScoreProps = BaseComponentProps & {
+    /**
+     * The numerical score to display. Must be a value between 0 and 100.
+     * Decimal values will be clamped to the nearest integer.
+     */
+    score: number;
+};

package/dist/shared/types/components/score.js

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

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

@@ -52,10 +52,12 @@ export interface CrmContext extends BaseContext {
 /** @ignore */
 export interface SettingsContext extends BaseContext {
     location: 'settings';
+    extension?: AppContext;
 }
 /** @ignore */
 export interface AppHomeContext extends BaseContext {
     location: 'home';
+    extension?: AppContext;
 }
 /** @ignore */
 export interface GenericContext extends BaseContext {

package/dist/shared/types/extension-points.d.ts

@@ -115,9 +115,10 @@ export interface ExtensionPoints extends _ExtensionPoints {
 }
 /** @ignore */
 export interface ExtensionPointApi<TExtensionPointLocation extends ExtensionPointLocation> {
-    runServerlessFunction: ServerlessFuncRunner;
     actions: ExtensionPoints[TExtensionPointLocation]['actions'];
     context: ExtensionPoints[TExtensionPointLocation]['context'];
+    /** @deprecated */
+    runServerlessFunction: ServerlessFuncRunner;
 }
 /**
  * The actions of the extension point API.
@@ -127,4 +128,8 @@ export type ExtensionPointApiActions<TExtensionPointLocation extends ExtensionPo
  * The context of the extension point API.
  */
 export type ExtensionPointApiContext<TExtensionPointLocation extends ExtensionPointLocation> = ExtensionPointApi<TExtensionPointLocation>['context'];
+/**
+ * The full API of the extension point.
+ */
+export type ExtensionPointFullApi<TExtensionPointLocation extends ExtensionPointLocation> = ExtensionPointApi<TExtensionPointLocation>;
 export {};

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

@@ -3,6 +3,6 @@ export type * from './actions.ts';
 export type * from './context.ts';
 export type * from './crm.ts';
 export type * from './extension-points.ts';
-export type * from './http-requests.ts';
+export * from './http-requests.ts';
 export type * from './reactions.ts';
 export * from './shared.ts';

package/dist/shared/types/index.js

@@ -1 +1,2 @@
+export * from "./http-requests.js"; // NOTE: `http-requests.ts` has some exported enums so we can't use `export type`
 export * from "./shared.js"; // NOTE: `shared.ts` has some exported classes so we can't use `export type` for now

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

@@ -240,5 +240,10 @@ export declare class RemoteEvent<V> {
     constructor(value: V, event: Event);
 }
 export interface BaseComponentProps {
+    /**
+     * Used by `findByTestId()` to locate this component in tests.
+     *
+     * @see {@link https://developers.hubspot.com/docs/apps/developer-platform/add-features/ui-extensibility/testing/reference#findbytestid | Testing utilities reference}
+     */
     testId?: string;
 }

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

@@ -1,6 +1,20 @@
 import { Logger } from './logger.ts';
 import { HubspotExtendFunction } from './extend.ts';
-import type { ExtensionPoints, ExtensionPointApiContext, ExtensionPointApiActions } from './extension-points.ts';
+import type { ExtensionPoints, ExtensionPointApiContext, ExtensionPointApiActions, ExtensionPointFullApi } from './extension-points.ts';
+export interface WorkersApi {
+    /**
+     * Hook added to worker globals so customer code can access extension context at runtime.
+     */
+    useExtensionContext: <ExtensionPoint extends keyof ExtensionPoints>() => ExtensionPointApiContext<ExtensionPoint>;
+    /**
+     * Hook added to worker globals so customer code can access extension actions at runtime.
+     */
+    useExtensionActions: <ExtensionPoint extends keyof ExtensionPoints>() => ExtensionPointApiActions<ExtensionPoint>;
+    /**
+     * Hook added to worker globals so customer code can access extension API at runtime.
+     */
+    useExtensionApi: <ExtensionPoint extends keyof ExtensionPoints>() => ExtensionPointFullApi<ExtensionPoint>;
+}
 export interface WorkerGlobalsInternal {
     /**
      * A marker that the current global is a HubSpot extension worker.
@@ -19,14 +33,5 @@ export interface WorkerGlobalsInternal {
      * Namespace where all HubSpot APIs that go on the worker should live.
      * This avoids polluting the global and reduces the possibility of customer code having collisions with our code.
      */
-    hsWorkerAPI: {
-        /**
-         * Hook added to worker globals so customer code can access extension context at runtime.
-         */
-        useExtensionContext: <ExtensionPoint extends keyof ExtensionPoints>() => ExtensionPointApiContext<ExtensionPoint>;
-        /**
-         * Hook added to worker globals so customer code can access extension actions at runtime.
-         */
-        useExtensionActions: <ExtensionPoint extends keyof ExtensionPoints>() => ExtensionPointApiActions<ExtensionPoint>;
-    };
+    hsWorkerAPI: WorkersApi;
 }

package/dist/testing/__tests__/mocks.useExtensionApi.spec.d.ts

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

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

@@ -0,0 +1,72 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { describe, expect, it } from 'vitest';
+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 })] }))] }));
+}
+function MyActionsCrmComponent() {
+    const { actions } = useExtensionApi();
+    return (_jsxs(_Fragment, { children: [_jsx(Button, { testId: "reloadButton", onClick: () => actions.reloadPage(), children: "Reload Page" }), _jsx(Button, { testId: "fetchButton", onClick: () => {
+                    actions.fetchCrmObjectProperties(['firstname', 'lastname']);
+                }, children: "Fetch Properties" })] }));
+}
+function MyActionsHomeComponent() {
+    const { actions } = useExtensionApi();
+    return (_jsx(_Fragment, { children: _jsx(Button, { testId: "copyButton", onClick: () => actions.copyTextToClipboard('Hello world'), children: "Copy Text" }) }));
+}
+describe('mock useExtensionApi', () => {
+    it('should provide a CRM mock implementation', () => {
+        const { render, findByTestId } = createRenderer('crm.record.tab');
+        render(_jsx(MyComponent, {}));
+        expect(findByTestId(Text, 'location-text').text).toEqual('crm.record.tab');
+        expect(findByTestId(Text, 'user-email').text).toEqual('fake_email@example.com');
+        expect(findByTestId(Text, 'user-firstName').text).toEqual('fake_firstName');
+        expect(findByTestId(Text, 'user-lastName').text).toEqual('fake_lastName');
+        expect(findByTestId(Text, 'portal-id').text).toEqual('123');
+        expect(findByTestId(Text, 'portal-timezone').text).toEqual('America/New_York');
+        expect(findByTestId(Text, 'crm-objectId').text).toEqual('123');
+        expect(findByTestId(Text, 'crm-objectTypeId').text).toEqual('0-1');
+    });
+    it('should provide a generic mock implementation without CRM properties', () => {
+        const { render, findByTestId, maybeFindByTestId } = createRenderer('settings');
+        render(_jsx(MyComponent, {}));
+        expect(findByTestId(Text, 'location-text').text).toEqual('settings');
+        expect(findByTestId(Text, 'user-email').text).toEqual('fake_email@example.com');
+        expect(findByTestId(Text, 'user-firstName').text).toEqual('fake_firstName');
+        expect(findByTestId(Text, 'user-lastName').text).toEqual('fake_lastName');
+        expect(findByTestId(Text, 'portal-id').text).toEqual('123');
+        expect(findByTestId(Text, 'portal-timezone').text).toEqual('America/New_York');
+        // doesn't have the CRM properties
+        expect(maybeFindByTestId(Text, 'crm-objectId')).toBeNull();
+        expect(maybeFindByTestId(Text, 'crm-objectTypeId')).toBeNull();
+    });
+    it('should use the mutated context', () => {
+        const newName = 'Gracie';
+        const { render, findByTestId, mocks } = createRenderer('settings');
+        mocks.context.user.firstName = newName;
+        render(_jsx(MyComponent, {}));
+        // no longer has the default context value, it has the mutate context
+        expect(findByTestId(Text, 'user-firstName').text).toEqual(newName);
+        // other properties stay the same
+        expect(findByTestId(Text, 'location-text').text).toEqual('settings');
+    });
+    it('should provide the ability to spy on the actions for the "crm.record.tab" extension point', () => {
+        const { mocks, render, findByTestId } = createRenderer('crm.record.tab');
+        const { actions } = mocks;
+        render(_jsx(MyActionsCrmComponent, {}));
+        findByTestId(Button, 'reloadButton').trigger('onClick');
+        expect(actions.reloadPage.callCount).toBe(1);
+        findByTestId(Button, 'fetchButton').trigger('onClick');
+        expect(actions.fetchCrmObjectProperties.callCount).toBe(1);
+    });
+    it('should provide the ability to spy on the actions for the "home" extension point', () => {
+        const { mocks, render, findByTestId } = createRenderer('home');
+        const { actions } = mocks;
+        render(_jsx(MyActionsHomeComponent, {}));
+        findByTestId(Button, 'copyButton').trigger('onClick');
+        expect(actions.copyTextToClipboard.callCount).toBe(1);
+    });
+});

package/dist/testing/internal/mocks/mock-hooks.js

@@ -69,5 +69,14 @@ export const createMockHooks = () => {
             return mocks
                 .actions;
         },
+        useExtensionApi: () => {
+            const mocks = useMocksContext();
+            return {
+                context: mocks.context,
+                actions: mocks
+                    .actions,
+                runServerlessFunction: mocks.runServerlessFunction,
+            };
+        },
     };
 };

package/dist/testing/internal/types-internal.d.ts

@@ -4,6 +4,7 @@ import { HubSpotReactComponent, UnknownComponentProps } from '../../shared/types
 import { useAssociations, useCrmProperties } from '../../crm/index.ts';
 import { useExtensionContext } from '../../hooks/useExtensionContext.tsx';
 import { useExtensionActions } from '../../hooks/useExtensionActions.tsx';
+import { useExtensionApi } from '../../hooks/useExtensionApi.tsx';
 import type { ElementMatcher, RenderedElementNode, RenderedFragmentNode, RenderedNode, RenderedParentNode, RenderedRootNode, RenderedTextNode } from '../types.ts';
 export type RemoteChildNode = RemoteComponent<any, RemoteRoot> | RemoteText<RemoteRoot>;
 export type RemoteParentNode = RemoteRoot | RemoteComponent<any, RemoteRoot> | RemoteFragment;
@@ -63,6 +64,7 @@ export interface RendererMockHooksInternal {
     useAssociations: typeof useAssociations;
     useExtensionContext: typeof useExtensionContext;
     useExtensionActions: typeof useExtensionActions;
+    useExtensionApi: typeof useExtensionApi;
 }
 export type RendererMocksInternal<TExtensionPointLocationName extends ExtensionPointLocation = ExtensionPointLocation> = RendererMockHooksInternal & ExtensionPointApi<TExtensionPointLocationName>;
 export type AnyFunction = (...args: any[]) => any;

package/dist/testing/types.d.ts

@@ -6,6 +6,7 @@ import { useAssociations, useCrmProperties } from '../crm/index.ts';
 import { useExtensionContext } from '../hooks/useExtensionContext.tsx';
 import { AnyFunction } from './internal/types-internal.ts';
 import { useExtensionActions } from '../hooks/useExtensionActions.tsx';
+import { useExtensionApi } from '../hooks/useExtensionApi.tsx';
 /**
  * The type of a rendered node.
  */
@@ -297,6 +298,15 @@ export interface RendererSpies<TExtensionPointLocation extends ExtensionPointLoc
      * information about spies and the supported API.
      */
     useExtensionActions: FunctionSpy<typeof useExtensionActions>;
+    /**
+     * A spy for the `useExtensionApi` 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.
+     */
+    useExtensionApi: FunctionSpy<typeof useExtensionApi>;
     /**
      * Mock context object that contains fake context data for the extension point API.
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hubspot/ui-extensions",
-  "version": "0.11.6",
+  "version": "0.12.1",
   "description": "",
   "type": "module",
   "main": "dist/index.js",
@@ -28,7 +28,8 @@
     "./crm": "./dist/crm/index.js",
     "./pages/home": "./dist/pages/home/index.js",
     "./experimental": "./dist/experimental/index.js",
-    "./testing": "./dist/testing/index.js"
+    "./testing": "./dist/testing/index.js",
+    "./hs-internal": "./dist/hs-internal/index.js"
   },
   "license": "MIT",
   "dependencies": {
@@ -74,5 +75,5 @@
   "tsd": {
     "directory": "src/__tests__/test-d"
   },
-  "gitHead": "12a14abf6ad776b12204dc37467a7c665a806adb"
+  "gitHead": "3da4a07183d48528ef431d46a8d327c053c4fe94"
 }