@hubspot/ui-extensions 0.11.5 → 0.12.0

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

@@ -5,9 +5,21 @@ import { BaseComponentProps } from '../shared.ts';
  * @category Component Props
  */
 export interface IllustrationProps extends BaseComponentProps {
+    /**
+     * The name of the illustration.
+     */
     name: IllustrationNames;
+    /**
+     * The illustration's alt text for accessibility.
+     */
     alt: string;
+    /**
+     * The width of the illustration in pixels.
+     */
     width?: number;
+    /**
+     * The height of the illustration in pixels.
+     */
     height?: number;
 }
 export declare const illustrationNames: {

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

@@ -7,23 +7,28 @@ import { ReactionsHandler } from '../reactions.ts';
  */
 export interface ImageProps extends OverlayComponentProps, BaseComponentProps {
     /**
-     * The alt text for the image.
+     * The alt text for the image, similar to the `alt` attribute for the HTML img tag.
      *
      */
     alt?: string;
     /**
-     * If provided, will be used as the href that will be opened in a new browser tab on click.
+     * When provided, sets the URL that will open when the image is clicked. Contains 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. By default:
+     *   - Links to HubSpot app pages will open in the same tab.
+     *   - Links to non-HubSpot app pages will open in a new tab.
      *
+     * When an image includes both `href` and an `onClick` action, both will be executed on button click.
      */
     href?: HrefProp;
     /**
-     * A function that will be called when the image is clicked.
+     * A function that will be called when the image is clicked. This function will receive no arguments and any returned values will be ignored.
      *
      * @event
      */
     onClick?: ReactionsHandler<ExtensionEvent>;
     /**
-     * The URL of the image to display.
+     * The source of the image display. You can specify a URL or you can import the image directly if it's within your project.
      *
      */
     src: 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

@@ -5,11 +5,11 @@ import { BaseComponentProps } from '../shared.ts';
  * */
 interface BaseInputProps<T = string, V = string> extends BaseComponentProps {
     /**
-     * The label text to display for the form input element.
+     * The text that displays above the input. Required if `inputType` is not set to `hidden`.
      */
     label: string;
     /**
-     * The unique identifier for the input element, this could be thought of as the HTML5 [Input element's name attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#name).
+     * The input's unique identifier, similar to the HTML input element name attribute.
      */
     name: string;
     /**
@@ -17,31 +17,31 @@ interface BaseInputProps<T = string, V = string> extends BaseComponentProps {
      */
     value?: T;
     /**
-     * Determines if the required indicator should be displayed.
+     * When set to `true`, displays a required field indicator.
      *
      * @defaultValue `false`
      */
     required?: boolean;
     /**
-     * Determines if the field is editable or not.
+     * When set to `true`, users will not be able to enter a value into the field.
      *
      * @defaultValue `false`
      */
     readOnly?: boolean;
     /**
-     * Instructional message to display to the user to help understand the purpose of the input.
+     * Displayed text that describes the field's purpose.
      */
     description?: string;
     /**
-     * Text that will appear in a tooltip next to the input label.
+     * The text that displays in a tooltip next to the input label.
      */
     tooltip?: string;
     /**
-     * Text that appears in the input when it has no value set.
+     * The text that appears in the input before a value is set.
      */
     placeholder?: string;
     /**
-     * If set to `true`, `validationMessage` is displayed as an error message, if it was provided. The input will also render its error state to let the user know there is an error. If set to `false`, `validationMessage` is displayed as a success message.
+     * When set to `true`, `validationMessage` is displayed as an error message if provided. The input will also render in an error state so that users are aware. If left `false`, `validationMessage` is displayed as a success message.
      *
      * @defaultValue `false`
      */
@@ -51,29 +51,29 @@ interface BaseInputProps<T = string, V = string> extends BaseComponentProps {
      */
     defaultValue?: T;
     /**
-     * The text to show under the input for error or success validations.
+     * The text to show if the input has an error.
      */
     validationMessage?: string;
     /**
-     * A callback function that is invoked when the value is committed. Currently these times are `onBlur` of the input and when the user submits the form.
+     * A callback function that is invoked when the value is committed. Currently, these are `onBlur` of the input and when the user submits the form.
      *
      * @event
      */
     onChange?: (value: V) => void;
     /**
-     * A function that is called and passed the value every time the field is edited by the user. It is recommended that you do not use this value to update state, that is what `onChange` should be used for. Instead this should be used for validation.
+     * A function that is called and passes the value when the field is edited by the user. Should be used for validation. It's recommended that you don't use this value to update state (use `onChange` instead).
      *
      * @event
      */
     onInput?: (value: V) => void;
     /**
-     * A function that is called and passed the value every time the field loses focus.
+     * A function that is called and passes the value when the field loses focus.
      *
      * @event
      */
     onBlur?: (value: V) => void;
     /**
-     * A function that is called and passed the value every time the field gets focused.
+     * A function that is called and passed the value when the field gets focused.
      *
      * @event
      */
@@ -86,7 +86,7 @@ interface BaseInputProps<T = string, V = string> extends BaseComponentProps {
  */
 export interface InputProps extends BaseInputProps {
     /**
-     * Sets the type of input to render.
+     * The type of input. An input with the `'password'` type will hide the characters that the user types.
      *
      * @defaultValue `"text"`
      */
@@ -103,7 +103,7 @@ export interface TextAreaProps extends BaseInputProps {
      */
     cols?: number;
     /**
-     * The maximum number of characters (UTF-16 code units) that the user can enter. If not specified, the max length is unlimited.
+     * The maximum number of characters (UTF-16 code units) that the user can enter. If not specified, maximum length is unlimited.
      */
     maxLength?: number;
     /**
@@ -111,7 +111,7 @@ export interface TextAreaProps extends BaseInputProps {
      */
     rows?: number;
     /**
-     * Sets whether the element is resizable, and if so in which directions.
+     * Sets whether the text field is resizable, and if so, in which directions.
      *
      * @defaultValue `"both"`
      */
@@ -137,21 +137,18 @@ type BaseInputForNumber = Omit<BaseInputProps<number, number>, 'onInput'>;
 export interface NumberInputProps extends BaseInputForNumber {
     /**
      * Sets the lower bound of the input.
-     *
      */
     min?: number;
     /**
      * Sets the upper bound of the input.
-     *
      */
     max?: number;
     /**
      * Sets the number of digits to the right of the decimal point.
-     *
      */
     precision?: number;
     /**
-     * Formats the input as a decimal point (decimal) or percentage (percentage).
+     * Formats the input as a decimal or percentage.
      *
      * @defaultValue `"decimal"`
      */
@@ -171,16 +168,15 @@ export interface CurrencyInputProps extends BaseInputForNumber {
      */
     currency?: string;
     /**
-     * Sets the number of decimal places for the currency
-     * If not provided, defaults to currency-specific precision
+     * Sets the number of decimal places for the currency. If not provided, defaults to currency-specific precision.
      */
     precision?: number;
     /**
-     * Sets the lower bound of the input
+     * Sets the lower bound of the input (handled by underlying component).
      */
     min?: number;
     /**
-     * Sets the upper bound of the input
+     * Sets the upper bound of the input (handled by underlying component).
      */
     max?: number;
 }
@@ -190,20 +186,18 @@ export interface CurrencyInputProps extends BaseInputForNumber {
  * @category Component Props
  */
 export interface StepperInputProps extends Omit<NumberInputProps, 'onInput'> {
-    /** The amount that the current value will increase or decrease on each step button click.
+    /** The amount that the current value will increase or decrease by. Default is `1`.
      * @defaultValue `1`
      */
     stepSize?: number;
     /**
-     * Text that will appear in a tooltip next to the step up button when users
-     * can't increase the current value.
+     * Text that will appear in a tooltip when the user has reached the minimum value.
      */
-    maxValueReachedTooltip?: string;
+    minValueReachedTooltip?: string;
     /**
-     * Text that will appear in a tooltip next to the step down button when users
-     * can't decrease the current value.
+     * Text that will appear in a tooltip when the user has reached the maximum value.
      */
-    minValueReachedTooltip?: string;
+    maxValueReachedTooltip?: string;
 }
 /** Object that represents dates. */
 export interface BaseDate {
@@ -231,60 +225,64 @@ type BaseDateInputForDate = Omit<BaseInputProps<BaseDate | null, DateInputEvents
  */
 export interface DateInputProps extends BaseDateInputForDate {
     /**
-     * Sets the earliest date that will be valid.
+     * Sets the earliest valid date available using the following format: `{ year: number; month: number; date: number }`
      */
     min?: BaseDate;
     /**
-     * Sets the latest date that will be valid.
+     * Sets the latest valid date available using the following format: `{ year: number; month: number; date: number }`
      */
     max?: BaseDate;
     /**
      * Sets the message that users will see when they hover over dates before the min date.
-     *
-     * @defaultValue `"You must choose a newer date"`
      */
     minValidationMessage?: string;
     /**
      * Sets the message that users will see when the hover over dates after the max date.
-     *
-     * @defaultValue `"You must choose an older date"`
      */
     maxValidationMessage?: string;
     /**
-     * Sets the date format that input will display to users.
+     * The date format.
      *
-     * @defaultValue `short`
+     * - `short`: 09/04/1986
+     * - `long`: September 4, 1986
+     * - `medium`: Sep 4, 1986
+     * - `standard`: 1986-09-04
+     * - `YYYY-MM-DD`: 1986-09-04
+     * - `L`: 09/04/1986
+     * - `LL`: September 4, 1986
+     * - `ll`: Sep 4, 1986
      *
-     * #### Format Options
-     *
-     * - short: `09/04/1986`
-     * - long: `September 4, 1986`
-     * - medium : `Sep 4, 1986`
-     * - standard: `1986-09-04`
-     * - L: `09/04/1986`
-     * - LL: `September 4, 1986`
-     * - ll : `Sep 4, 1986`
-     * - YYYY-MM-DD: `1986-09-04`
+     * @defaultValue `'short'`
      */
     format?: 'YYYY-MM-DD' | 'L' | 'LL' | 'll' | 'short' | 'long' | 'medium' | 'standard';
     /**
-     * Sets the timezone that the component will use to calculate valid dates.
+     * Sets the label of the button that clears the date.
+     */
+    clearButtonLabel?: string;
+    /**
+     * Sets the label of the button that inserts today's date.
+     */
+    todayButtonLabel?: string;
+    /**
+     * Sets the timezone that the component will user to calculate valid dates.
      *
-     * @defaultValue `"userTz"`
+     * - `userTz` (default): the user's time zone.
+     * - `portalTz`: the portal's default time zone.
+     *
+     * @defaultValue `'userTz'`
      */
     timezone?: 'userTz' | 'portalTz';
     /**
-     * Sets the label of the clear button.
-     *
-     * @defaultValue `"Clear"`
+     * 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).
      */
-    clearButtonLabel?: string;
+    value?: BaseDate;
     /**
-     * Sets the label of the today button.
-     *
-     * @defaultValue `"Today"`
+     * The default date value. Uses the same format as the value field.
      */
-    todayButtonLabel?: string;
+    defaultValue?: BaseDate;
 }
 /**
  * Object that represents times.
@@ -320,11 +318,11 @@ export interface TimeInputProps extends BaseTimeInputForTime {
      */
     onChange?: (value: TimeInputEventsPayload) => void;
     /**
-     * Sets the earliest time that will be valid.
+     * Sets the earliest valid time available.
      */
     min?: BaseTime;
     /**
-     * Sets the latest time that will be valid.
+     * Sets the latest valid time available.
      */
     max?: BaseTime;
     /**
@@ -334,7 +332,7 @@ export interface TimeInputProps extends BaseTimeInputForTime {
      */
     interval?: number;
     /**
-     * Sets the timezone that the component will display alongside times in the TimeInput. This will not modify the available valid inputs.
+     * Sets the timezone that the component will use to calculate valid times.
      *
      */
     timezone?: 'userTz' | 'portalTz';
@@ -345,7 +343,7 @@ export interface TimeInputProps extends BaseTimeInputForTime {
  * @category Component Props
  */
 export interface SearchInputProps extends BaseInputProps {
-    /** Shows a clear button to clear the input. Default is true. */
+    /** When set to `true`, shows a clear button to clear the input. Default is `true`. */
     clearable?: boolean;
 }
 export {};

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

@@ -51,7 +51,7 @@ export interface FlexProps extends BaseComponentProps {
      */
     children?: ReactNode;
     /**
-     * Arranges components `horizontally` or `vertically` by setting the main axis.
+     * Arranges the components horizontally or vertically by setting the main axis.
      *
      * @defaultValue `"row"`
      */
@@ -69,12 +69,11 @@ export interface FlexProps extends BaseComponentProps {
      */
     align?: FlexAlign;
     /**
-     * Overrides Flex's `alignItem` value for this element.
-     *
+     * Distributes a child component along the cross-axis using the available free space. Use this prop for nested `Flex` and `Box` components to align them differently from other child components in the `Flex` group.
      */
     alignSelf?: FlexAlign;
     /**
-     * Whether components will wrap instead of trying to fit on one line.
+     * Whether components will wrap rather than trying to fit on one line.
      *
      * @defaultValue `"nowrap"`
      */
@@ -92,21 +91,19 @@ export interface BoxProps extends BaseComponentProps {
      */
     children: ReactNode;
     /**
-     * Overrides Flex's `alignItem` value for this element.
+     * Distributes a child component along the cross-axis using the available free space. Use this prop for nested `Box` components to align them differently from other child components in the `Flex` group.
      *
      * @defaultValue `"auto"`
      */
     alignSelf?: 'start' | 'center' | 'baseline' | 'end' | 'stretch' | 'auto';
     /**
-     * Sets how the item will grow or shrink when it's a direct ancestor of the Flex component.
-     * ##### Options in detail
-     *
-     *- `initial`: The item is sized according to its width and height properties. It shrinks to its minimum size to fit the container, but does not grow to absorb any extra free space in the flex container.
-     *- `auto`: The item is sized according to its width and height properties, but grows to absorb any extra free space in the flex container, and shrinks to its minimum size to fit the container.
-     *- `none`: The item is sized according to its width and height properties. It is fully inflexible: it neither shrinks nor grows in relation to the flex container.
-     *- `number`:  Tells a component to fill all available space, shared evenly amongst other components with the same parent. The larger the flex given, the higher the ratio of space a component will take compared to its siblings.
+     * Distributes components based on the available empty space around them. Options are as follows:
+     * - `initial`: The item is sized according to its width and height properties. It shrinks to its minimum size to fit the container, but does not grow to absorb any extra free space in the flex container.
+     * - `auto`: The item is sized according to its width and height properties, but grows to absorb any extra free space in the flex container, and shrinks to its minimum size to fit the container.
+     * - `none`: The item is sized according to its width and height properties. It is fully inflexible: it neither shrinks nor grows in relation to the flex container.
+     * - Number: tells a component to fill all available space, shared evenly amongst other components with the same parent. The larger the flex given, the higher the ratio of space a component will take compared to its siblings.
      *
-     * @defaultValue `"initial"`
+     * @defaultValue `"auto"`
      */
     flex?: 'initial' | 'auto' | 'none' | number;
 }
@@ -118,21 +115,22 @@ export interface BoxProps extends BaseComponentProps {
 export interface InlineProps extends BaseComponentProps {
     /**
      * Sets the content that will render inside the component. This prop is passed implicitly by providing sub-components.
-     *
      */
     children?: ReactNode;
     /**
      * Distributes components along the main axis using the available free space.
+     *
      * @defaultValue `"start"`
      */
     justify?: FlexJustify;
     /**
      * Distributes components along the cross-axis using the available free space.
-     * @defaultValue `"center"`
+     *
+     * @defaultValue `"stretch"`
      */
     align?: FlexAlign;
     /**
-     * Sets the spacing between components.
+     * The amount of spacing between components.
      *
      * @defaultValue `"flush"`
      */
@@ -145,26 +143,21 @@ export interface InlineProps extends BaseComponentProps {
  */
 export interface AutoGridProps extends BaseComponentProps {
     /**
-     * Sets the width of each column in the grid.
-     * When `flexible` is true, columns will be at least this width (or collapse to container width if smaller), then expand equally to fill available space.
-     * When `flexible` is false, columns are exactly this width.
+     * Sets width of each column in pixels. When `flexible` is `true`, acts as minimum width before expanding.
      */
     columnWidth: number;
     /**
-     * Sets the spacing between grid items.
+     * Sets spacing between grid items.
      *
      * @defaultValue `"flush"`
      */
     gap?: AllDistances;
     /**
      * Sets the content that will render inside the component. This prop is passed implicitly by providing sub-components.
-     *
      */
     children?: ReactNode;
     /**
-     * Whether columns should expand to fill available space.
-     * When true, columns will be at least `columnWidth` but grow equally to fill the container.
-     * When false, columns are exactly `columnWidth`.
+     * When `false`, columns have exact `columnWidth`. When `true`, columns expand equally to fill available space with `columnWidth` as the minimum.
      *
      * @defaultValue `false`
      */

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

@@ -13,24 +13,27 @@ export interface LinkProps extends OverlayComponentProps, BaseComponentProps {
      */
     children: ReactNode;
     /**
-     * The URL that will be opened on click. Links to pages in the HubSpot account will open in the same tab, while non-HubSpot links will open in a new tab.
-     *
+     * Sets the link's URL and open behavior. Contains 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:
+     *   - 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.
      */
     href: HrefProp;
     /**
-     * The color variation of the link.
+     * The color of the link.
      *
      * @defaultValue `"primary"`
      */
     variant?: 'primary' | 'destructive' | 'light' | 'dark';
     /**
-     * A function that will be invoked with the link is clicked.
+     * A function that is invoked when the link is clicked. The function receives no arguments and its return value is ignored.
      *
      * @event
      */
     onClick?: ReactionsHandler<ExtensionEvent>;
     /**
-     * When set to true, `event.preventDefault()` will be invoked before the `onClick` function is called, preventing automatic navigation to the href URL.
+     * When set to `true`, `event.preventDefault()` will be invoked before the `onClick` function is called, preventing automatic navigation to the href URL.
      *
      * @defaultValue `false`
      */

package/dist/shared/types/components/loading-spinner.d.ts

@@ -6,12 +6,12 @@ import { TShirtSizes, BaseComponentProps } from '../shared.ts';
  */
 export interface LoadingSpinnerProps extends BaseComponentProps {
     /**
-     * The text that displays next to the spinner. Note: the label is not shown by default, you must set `showLabel` to `true` to display the label.
+     * The text that displays next to the spinner.
      *
      */
     label: string;
     /**
-     * When set to `true`, the label will appear next to the spinner.
+     * When set to `true`, the `label` will appear next to the spinner.
      *
      * @defaultValue `false`
      */
@@ -23,7 +23,7 @@ export interface LoadingSpinnerProps extends BaseComponentProps {
      */
     size?: TShirtSizes['xs'] | TShirtSizes['sm'] | TShirtSizes['md'];
     /**
-     * The position of the spinner. Can be one of `inline` or `centered`.
+     * The position of the spinner.
      *
      * @defaultValue `"inline"`
      */

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

@@ -2,7 +2,7 @@ import { ReactNode } from 'react';
 import { TShirtSizes, BaseComponentProps } from '../shared.ts';
 export interface ModalProps extends BaseComponentProps {
     /**
-     * Accessibility label.
+     * The modal's accessibility label.
      *
      */
     'aria-label'?: string;
@@ -12,7 +12,7 @@ export interface ModalProps extends BaseComponentProps {
      */
     children?: ReactNode;
     /**
-     * A unique ID for the modal
+     * The unique identifier for the modal.
      *
      */
     id: string;
@@ -27,18 +27,18 @@ export interface ModalProps extends BaseComponentProps {
      */
     onClose?: () => void;
     /**
-     * The width of the modal
+     * The width of the modal.
      *
      * @defaultValue `"sm"`
      */
     width?: TShirtSizes['sm'] | TShirtSizes['md'] | TShirtSizes['lg'];
     /**
-     * The title of the modal
+     * The title of the modal, displayed at in the modal's top bar.
      *
      */
     title?: string;
     /**
-     * The variant of the modal
+     * The type of modal. See the [variants section](https://developers.hubspot.com/docs/apps/developer-platform/add-features/ui-extensibility/ui-components/standard-components/modal#variants) for more information.
      *
      * @defaultValue `"default"`
      */

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

@@ -2,7 +2,7 @@ import { ReactNode } from 'react';
 import { TShirtSizes, BaseComponentProps } from '../shared.ts';
 export interface PanelProps extends BaseComponentProps {
     /**
-     * Accessibility label.
+     * The panel's accessibility label.
      *
      */
     'aria-label'?: string;
@@ -12,7 +12,7 @@ export interface PanelProps extends BaseComponentProps {
      */
     children?: ReactNode;
     /**
-     * A unique ID for the panel
+     * A unique ID for the panel.
      *
      */
     id: string;
@@ -27,18 +27,18 @@ export interface PanelProps extends BaseComponentProps {
      */
     onClose?: () => void;
     /**
-     * The width of the panel
+     * The width of the panel.
      *
      * @defaultValue `"sm"`
      */
     width?: TShirtSizes['sm'] | TShirtSizes['md'] | TShirtSizes['lg'];
     /**
-     * The title of the panel
+     * The text that displays at the top of the panel.
      *
      */
     title?: string;
     /**
-     * The variant of the panel
+     * The panel variant. The `modal` variant includes better screen reader focus on the panel and is recommended for visual and motor accessibility and tab navigation. See [variants](https://developers.hubspot.com/docs/apps/developer-platform/add-features/ui-extensibility/ui-components/standard-components/panel#variants) for more information.
      *
      * @defaultValue `"default"`
      */
@@ -46,13 +46,13 @@ export interface PanelProps extends BaseComponentProps {
 }
 export interface PanelSectionProps extends BaseComponentProps {
     /**
-     * When set to `true`, the section will have no bottom margin
+     * When set to `true`, the section will have no bottom margin.
      *
      * @defaultValue `false`
      */
     flush?: boolean;
     /**
-     * The main content of the section
+     * The main content of the section.
      *
      */
     children: ReactNode;