@servicetitan/anvil2 2.7.0 → 2.8.0

package/dist/beta/components/SelectField/types.d.ts

@@ -1,5 +1,5 @@
-import { AriaAttributes, CSSProperties, ReactElement, ReactNode } from 'react';
-import { LayoutUtilProps, Size } from '../../../types';
+import { AriaAttributes, CSSProperties, ReactElement } from 'react';
+import { AiMarkWithTooltipOrPopoverProps, LayoutUtilProps, Size } from '../../../types';
 import { AvatarProps, ChipProps, IconProps } from '../../..';
 /**
  * Configuration options for the SelectField cache.
@@ -187,10 +187,10 @@ type SelectFieldCommonSelectFieldProps = {
      */
     hint?: ReactElement | string;
     /**
-     * Custom ReactNode to render as the label, overriding the default label text.
-     * The `label` prop is still required for accessibility purposes.
+     * AI mark configuration to display next to the label.
+     * Can be a boolean to show a simple AI mark, or an object with tooltip/popover configuration.
      */
-    labelNode?: ReactNode;
+    labelAiMark?: AiMarkWithTooltipOrPopoverProps["aiMark"];
     /**
      * Description text displayed below the input field.
      */

package/dist/beta/components/SelectMenu/internal/useMenuInteraction.d.ts

@@ -12,6 +12,8 @@ export type UseMenuInteractionConfig = {
     id: string;
     triggerRef: RefObject<HTMLButtonElement>;
     label: string;
+    onImplicitClose?: () => void;
+    onExplicitClose?: () => void;
 };
 export type MenuTriggerProps = {
     ref: RefObject<HTMLButtonElement>;
@@ -54,7 +56,7 @@ type ItemReturnProps = {
 };
 export type GetMenuPropsFn = (opts?: MenuPropsArg) => MenuReturnProps;
 export type GetItemPropsFn = (opts: ItemPropsArg) => ItemReturnProps;
-export declare const useMenuInteraction: ({ items, sectionsMeta: _sectionsMeta, onItemActivate, selectedItemIds, displayAs: _displayAs, closeOnActivate, disabled, id, triggerRef, label, }: UseMenuInteractionConfig) => {
+export declare const useMenuInteraction: ({ items, sectionsMeta: _sectionsMeta, onItemActivate, selectedItemIds, displayAs: _displayAs, closeOnActivate, disabled, id, triggerRef, label, onImplicitClose, onExplicitClose, }: UseMenuInteractionConfig) => {
     isOpen: boolean;
     openMenu: () => void;
     closeMenu: (options?: {

package/dist/beta/components/SelectMenu/types.d.ts

@@ -52,6 +52,21 @@ type SelectMenuCommonProps = {
      * Render function that receives trigger props and returns the element that opens the menu.
      */
     trigger: (props: SelectMenuTriggerProps) => ReactElement;
+    /**
+     * Called when a key is pressed inside the menu (search field or listbox), before the
+     * menu's own key handling. Use `e.preventDefault()` to suppress the default behavior.
+     */
+    onMenuKeyDown?: (e: KeyboardEvent) => void;
+    /**
+     * Called when the menu closes implicitly — due to Tab navigation, clicking outside,
+     * or other ambient focus loss. Focus is not restored to the trigger in these cases.
+     */
+    onImplicitClose?: () => void;
+    /**
+     * Called when the menu closes explicitly — the user intentionally dismissed it
+     * via Escape, selecting an option, or toggling the trigger. Focus is restored to the trigger.
+     */
+    onExplicitClose?: () => void;
     /**
      * Accessible label for the menu. Used by screen readers but not rendered visually.
      */

package/dist/beta/components/Table/DataTable/DataTable.d.ts

@@ -1,21 +1,8 @@
 import { ComponentPropsWithoutRef, Ref, ReactNode } from 'react';
 import { LayoutUtilProps } from '../../../../types';
 import { ColumnDef, CustomTableFooterCellProps, TableRow } from '../types';
-import { DataTableEmptyState, DataTablePaginationConfig, DataTableRef } from './types';
-export type { DataTableRef, DataTableEmptyState };
-/**
- * Represents a sorted column configuration for DataTable
- */
-export type SortedColumn = {
-    /**
-     * The column identifier
-     */
-    id: string;
-    /**
-     * Whether the column is sorted in descending order
-     */
-    desc: boolean;
-};
+import { DataTableCacheOptions, DataTableEmptyState, DataTablePaginationConfig, DataTableRef, SortedColumn } from './types';
+export type { DataTableCacheOptions, DataTableRef, DataTableEmptyState, SortedColumn, };
 /**
  * Props for the DataTable component
  * @extends LayoutUtilProps

package/dist/beta/components/Table/DataTable/internal/editable-cells/DataTableEditableMultiselectAsyncCell.d.ts

@@ -0,0 +1,35 @@
+import { EditableCellImperativeHandle, BaseEditableCellProps } from './types';
+export type DataTableEditableMultiselectAsyncCellProps<T> = BaseEditableCellProps<T>;
+/**
+ * Renders an async editable multiselect cell in a DataTable. This component provides a
+ * MultiSelectMenu popover that loads options asynchronously via a `loadOptions` function.
+ * The loader receives a `context` object containing the current row data, enabling per-row
+ * option loading.
+ *
+ * Features:
+ * - Supports all four MultiSelectMenu lazy variants: eager, page, offset, and group
+ * - Passes row context to `loadOptions` for per-row async option loading
+ * - Auto-disables caching by default to prevent cross-row cache pollution
+ * - Supports full MultiSelectMenu passthrough props (debounceMs, virtualize, selectAll, etc.)
+ * - Live selection: `onChange` fires on each toggle
+ * - Keyboard navigation consistent with other editable cell types
+ *
+ * **Value contract**: Unlike `mode: "multiselect"` (which stores ID arrays), the cell value
+ * must be `MultiSelectMenuOption[]` — full option objects. The consumer stores them wholesale
+ * from the `onChange` callback.
+ *
+ * @param props - The props for the DataTableEditableMultiselectAsyncCell component
+ * @param props.cell - The TanStack table cell instance
+ * @param props.cellProps - Props for styling and event handling of the cell container
+ * @param props.cellPosition - The position of the cell in the table
+ * @param props.children - The content to display when not editing
+ * @param props.isHovered - Whether the cell is currently hovered
+ * @param ref - Ref to the imperative handle for programmatic control
+ * @returns The rendered async editable multiselect cell component
+ */
+export declare function DataTableEditableMultiselectAsyncCellInner<T>(props: DataTableEditableMultiselectAsyncCellProps<T>, ref: React.Ref<EditableCellImperativeHandle>): import("react/jsx-runtime").JSX.Element;
+export declare const DataTableEditableMultiselectAsyncCell: (<T>(props: DataTableEditableMultiselectAsyncCellProps<T> & {
+    ref?: React.Ref<EditableCellImperativeHandle>;
+}) => React.ReactElement) & {
+    displayName: string;
+};

package/dist/beta/components/Table/DataTable/internal/editable-cells/DataTableEditableMultiselectCell.d.ts

@@ -1,9 +1,10 @@
 import { EditableCellImperativeHandle, BaseEditableCellProps } from './types';
 export type DataTableEditableMultiselectCellProps<T> = BaseEditableCellProps<T>;
 /**
- * Renders an editable multiselect cell in a DataTable. This component provides a popover with a
- * searchable list that appears when the cell is activated, allowing users to select multiple values
- * from a list of options. Supports keyboard navigation, search filtering, and commit/cancel operations.
+ * Renders an editable multiselect cell in a DataTable. This component provides a
+ * MultiSelectMenu popover with search that appears when the cell is activated, allowing
+ * users to select multiple values from a list of options. Supports keyboard navigation
+ * and live selection.
  *
  * @param props - The props for the DataTableEditableMultiselectCell component
  * @param props.cell - The TanStack table cell instance

package/dist/beta/components/Table/DataTable/internal/editable-cells/DataTableEditableSelectAsyncCell.d.ts

@@ -0,0 +1,7 @@
+import { EditableCellImperativeHandle, BaseEditableCellProps } from './types';
+export type DataTableEditableSelectAsyncCellProps<T> = BaseEditableCellProps<T>;
+export declare const DataTableEditableSelectAsyncCell: (<T>(props: DataTableEditableSelectAsyncCellProps<T> & {
+    ref?: React.Ref<EditableCellImperativeHandle>;
+}) => React.ReactElement) & {
+    displayName: string;
+};

package/dist/beta/components/Table/DataTable/internal/editable-cells/useEditableMenuCell.d.ts

@@ -0,0 +1,34 @@
+import { CellPosition } from '../../../internal/types';
+import { EditableCellImperativeHandle, EditableCellCellProps } from './types';
+type UseEditableMenuCellOptions = {
+    cellPosition: CellPosition;
+    onCellKeyDown: EditableCellCellProps["onKeyDown"];
+    ref: React.Ref<EditableCellImperativeHandle>;
+};
+/**
+ * Shared hook for select/multiselect editable DataTable cells that use a menu-based
+ * editing UX (SelectMenu, MultiSelectMenu, and their async variants).
+ *
+ * Encapsulates the common state, refs, imperative handle, keyboard/focus/mouse handlers,
+ * and focus context value that are identical across all four menu-based cell components.
+ *
+ * @param options.cellPosition - The position of the cell in the table grid
+ * @param options.onCellKeyDown - The cell's keyDown handler from cellProps, forwarded when the menu is closed
+ * @param options.ref - Ref for the imperative handle (invoke/focus)
+ * @returns Shared state, refs, event handlers, and cellFocusContextValue
+ */
+export declare function useEditableMenuCell({ cellPosition, onCellKeyDown, ref, }: UseEditableMenuCellOptions): {
+    tabIndex: number;
+    cellRef: import('react').RefObject<HTMLTableCellElement>;
+    triggerClickRef: import('react').MutableRefObject<(() => void) | null>;
+    handleCellKeyDown: (event: React.KeyboardEvent<HTMLElement>, menuKeyDown: ((event: React.KeyboardEvent<HTMLButtonElement>) => void) | undefined, isOpen: boolean) => void;
+    handleMenuKeyDown: (e: React.KeyboardEvent) => void;
+    handleImplicitClose: () => void;
+    handleCellMouseDown: (triggerOnClick: () => void) => () => void;
+    handleCellBlur: (e: React.FocusEvent<HTMLElement>) => void;
+    handleCellFocus: (event: React.FocusEvent<HTMLTableCellElement>) => void;
+    cellFocusContextValue: {
+        isCellFocused: boolean;
+    };
+};
+export {};

package/dist/beta/components/Table/DataTable/internal/usePageDataCache.d.ts

@@ -0,0 +1,29 @@
+import { TableRow } from '../../types';
+import { DataTableCacheOptions, SortedColumn } from '../types';
+/**
+ * Hook for caching resolved page data in DataTable.
+ *
+ * Features:
+ * - Caches resolved page data per page index using a Map stored in a ref
+ * - Returns cached data synchronously on cache hit, avoiding unnecessary API calls
+ * - Synchronously clears cache during render when invalidation triggers change
+ * - Size-based eviction (FIFO) when cache exceeds maxSize: oldest entry is dropped to make room
+ *
+ * @param config - Configuration including loadPageData function, cache options, and invalidation triggers
+ * @returns Object containing getOrLoad function and clearCache function
+ */
+export declare function usePageDataCache<T>(config: {
+    loadPageData?: (params: {
+        pageIndex: number;
+        pageSize: number;
+        sorting?: SortedColumn;
+    }) => TableRow<T>[] | Promise<TableRow<T>[]>;
+    cache?: DataTableCacheOptions;
+    refreshKey?: string | number;
+    refreshCounter: number;
+    rowsPerPage: number;
+    sorting?: SortedColumn;
+}): {
+    getOrLoad: (pageIndex: number, pageSize: number, sorting?: SortedColumn) => TableRow<T>[] | Promise<TableRow<T>[]>;
+    clearCache: () => void;
+};

package/dist/beta/components/Table/DataTable/internal/util/getTanStackColumnDef.d.ts

@@ -1,12 +1,10 @@
 import { ColumnDef as TanstackColumnDef } from '@tanstack/react-table';
 import { ReactNode } from 'react';
-import { ColumnDef } from '../../../types';
+import { ColumnDef, EditMode } from '../../../types';
 declare module "@tanstack/react-table" {
     interface ColumnMeta<TData, TValue> {
-        editMode?: ColumnDef<TData>["editMode"];
+        editMode?: EditMode;
         editConfig?: ColumnDef<TData>["editConfig"];
-        onChange?: ColumnDef<TData>["onChange"];
-        options?: ColumnDef<TData>["options"];
         /**
          * The original column definition, stored for type narrowing and runtime access
          */

package/dist/beta/components/Table/DataTable/types.d.ts

@@ -1,6 +1,19 @@
 import { ReactNode } from 'react';
 import { TableRow } from '../types';
 import { Svg } from '../../../../types';
+/**
+ * Represents a sorted column configuration for DataTable
+ */
+export type SortedColumn = {
+    /**
+     * The column identifier
+     */
+    id: string;
+    /**
+     * Whether the column is sorted in descending order
+     */
+    desc: boolean;
+};
 /**
  * Configuration for the empty state displayed when the DataTable has no data
  */
@@ -19,6 +32,26 @@ export type DataTableEmptyState = {
      */
     content?: ReactNode;
 };
+/**
+ * Configuration for caching loadPageData results in DataTable.
+ * When enabled, resolved page data is cached per page index, allowing
+ * instant restoration when returning to a previously loaded page.
+ * @property {boolean} [enabled] - Whether caching is enabled. Defaults to true.
+ * @property {number} [maxSize] - Maximum number of pages to cache. Oldest entry is evicted (FIFO) when the limit is reached. Defaults to 15.
+ */
+export type DataTableCacheOptions = {
+    /**
+     * Whether caching is enabled.
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Maximum number of pages to cache. When the limit is reached, the oldest cached page is
+     * evicted (FIFO) to make room for the new entry.
+     * @default 15
+     */
+    maxSize?: number;
+};
 /**
  * Configuration for pagination in DataTable
  */
@@ -45,10 +78,14 @@ export type DataTablePaginationConfig<T> = {
      * Function to get the data for the current page. When used, the data displayed will be
      * fully controlled by the implementor. This is useful for server-side pagination scenarios where
      * the total number of rows may differ from the data array length.
+     *
+     * The `sorting` parameter is provided when a column is sorted, allowing the server
+     * to return data in the correct sort order.
      */
-    loadPageData?: ({ pageIndex, pageSize, }: {
+    loadPageData?: ({ pageIndex, pageSize, sorting, }: {
         pageIndex: number;
         pageSize: number;
+        sorting?: SortedColumn;
     }) => TableRow<T>[] | Promise<TableRow<T>[]>;
     /**
      * Default page index for uncontrolled mode (0-based)
@@ -75,10 +112,16 @@ export type DataTablePaginationConfig<T> = {
      * When changed, the page index automatically resets to 0.
      */
     refreshKey?: string | number;
+    /**
+     * Configuration for caching loadPageData results.
+     * Caching is enabled by default. Set `{ enabled: false }` to disable.
+     */
+    cache?: DataTableCacheOptions;
 };
 /**
  * Ref handle for DataTable component
  * @property {function} refresh - Triggers a data refetch and resets the page index to 0. Useful for manually refreshing data after external changes (e.g., after a mutation).
+ * @property {function} clearCache - Clears the page data cache without triggering a refetch.
  */
 export type DataTableRef = {
     /**
@@ -87,4 +130,8 @@ export type DataTableRef = {
      * When using controlled pagination, this will call `onPageChange(0)`.
      */
     refresh: () => void;
+    /**
+     * Clears the page data cache without triggering a refetch.
+     */
+    clearCache: () => void;
 };

package/dist/beta/components/Table/createColumnHelper.d.ts

@@ -1,11 +1,8 @@
 import { ReactNode } from 'react';
-import { ColumnDef, ColumnTypeConfig, TextEditConfig, NumberEditConfig, SelectEditConfig, MultiselectEditConfig, BooleanEditConfig, TableRow } from './types';
+import { ColumnDef, ColumnTypeConfig, TextEditConfig, NumberEditConfig, SelectEditConfig, SelectAsyncEditConfig, MultiselectEditConfig, MultiselectAsyncEditConfig, BooleanEditConfig, TableRow } from './types';
+import { MultiSelectMenuOption } from '../MultiSelectMenu';
 /**
- * Utility type that extracts the element type from an array type
- */
-type ArrayElement<T> = T extends (infer U)[] ? U : never;
-/**
- * Base column configuration without editMode-specific or editConfig-specific properties
+ * Base column configuration shared by all column types
  */
 type BaseColumnConfig<T, K extends keyof T> = {
     /**
@@ -70,9 +67,6 @@ type BaseColumnConfig<T, K extends keyof T> = {
  */
 type ReadOnlyColumnConfig<T, K extends keyof T> = BaseColumnConfig<T, K> & {
     editConfig?: undefined;
-    editMode?: undefined;
-    onChange?: never;
-    options?: never;
 };
 /**
  * Configuration for text editable columns using editConfig.
@@ -80,9 +74,6 @@ type ReadOnlyColumnConfig<T, K extends keyof T> = BaseColumnConfig<T, K> & {
  */
 type TextEditConfigColumnConfig<T, K extends keyof T> = NonNullable<T[K]> extends string ? BaseColumnConfig<T, K> & {
     editConfig: TextEditConfig<T, K>;
-    editMode?: undefined;
-    onChange?: undefined;
-    options?: undefined;
 } : never;
 /**
  * Configuration for number editable columns using editConfig.
@@ -90,18 +81,18 @@ type TextEditConfigColumnConfig<T, K extends keyof T> = NonNullable<T[K]> extend
  */
 type NumberEditConfigColumnConfig<T, K extends keyof T> = NonNullable<T[K]> extends number ? BaseColumnConfig<T, K> & {
     editConfig: NumberEditConfig<T, K>;
-    editMode?: undefined;
-    onChange?: undefined;
-    options?: undefined;
 } : never;
 /**
  * Configuration for select editable columns using editConfig
  */
 type SelectEditConfigColumnConfig<T, K extends keyof T> = BaseColumnConfig<T, K> & {
     editConfig: SelectEditConfig<T, K>;
-    editMode?: undefined;
-    onChange?: undefined;
-    options?: undefined;
+};
+/**
+ * Configuration for async select editable columns using editConfig
+ */
+type SelectAsyncEditConfigColumnConfig<T, K extends keyof T> = BaseColumnConfig<T, K> & {
+    editConfig: SelectAsyncEditConfig<T>;
 };
 /**
  * Configuration for multiselect editable columns using editConfig
@@ -109,9 +100,14 @@ type SelectEditConfigColumnConfig<T, K extends keyof T> = BaseColumnConfig<T, K>
  */
 type MultiselectEditConfigColumnConfig<T, K extends keyof T> = NonNullable<T[K]> extends unknown[] ? BaseColumnConfig<T, K> & {
     editConfig: MultiselectEditConfig<T, K>;
-    editMode?: undefined;
-    onChange?: undefined;
-    options?: undefined;
+} : never;
+/**
+ * Configuration for async multiselect editable columns using editConfig.
+ * Only valid when T[K] is MultiSelectMenuOption[] — full option objects,
+ * not a plain primitive array like string[].
+ */
+type MultiselectAsyncEditConfigColumnConfig<T, K extends keyof T> = NonNullable<T[K]> extends MultiSelectMenuOption[] ? BaseColumnConfig<T, K> & {
+    editConfig: MultiselectAsyncEditConfig<T>;
 } : never;
 /**
  * Configuration for boolean editable columns using editConfig.
@@ -119,53 +115,12 @@ type MultiselectEditConfigColumnConfig<T, K extends keyof T> = NonNullable<T[K]>
  */
 type BooleanEditConfigColumnConfig<T, K extends keyof T> = NonNullable<T[K]> extends boolean ? BaseColumnConfig<T, K> & {
     editConfig: BooleanEditConfig<T, K>;
-    editMode?: undefined;
-    onChange?: undefined;
-    options?: undefined;
-} : never;
-/**
- * Configuration for text editable columns (legacy).
- * Valid when T[K] is a string.
- * @deprecated Use editConfig instead: `editConfig: { mode: "text", onChange: ... }`
- */
-type TextEditableColumnConfig<T, K extends keyof T> = NonNullable<T[K]> extends string ? BaseColumnConfig<T, K> & {
-    editConfig?: undefined;
-    editMode: "text";
-    onChange?: (value: string, rowId: string) => void;
-    options?: never;
-} : never;
-/**
- * Configuration for select editable columns (legacy)
- * @deprecated Use editConfig instead: `editConfig: { mode: "select", options: [...], onChange: ... }`
- */
-type SelectEditableColumnConfig<T, K extends keyof T> = BaseColumnConfig<T, K> & {
-    editConfig?: undefined;
-    editMode: "select";
-    onChange?: (value: T[K], rowId: string) => void;
-    options: {
-        value: T[K];
-        label: string;
-    }[];
-};
-/**
- * Configuration for multiselect editable columns (legacy)
- * @deprecated Use editConfig instead: `editConfig: { mode: "multiselect", options: [...], onChange: ... }`
- */
-type MultiselectEditableColumnConfig<T, K extends keyof T> = NonNullable<T[K]> extends unknown[] ? BaseColumnConfig<T, K> & {
-    editConfig?: undefined;
-    editMode: "multiselect";
-    onChange?: (value: T[K], rowId: string) => void;
-    options: {
-        value: ArrayElement<NonNullable<T[K]>>;
-        label: string;
-    }[];
 } : never;
 /**
  * Full column configuration type - union of all possible configurations.
- * Includes both new editConfig-based and legacy editMode-based configs.
- * TypeScript will enforce that the editMode/editConfig matches the value type constraints.
+ * TypeScript will enforce that the editConfig matches the value type constraints.
  */
-type ColumnConfig<T, K extends keyof T> = ReadOnlyColumnConfig<T, K> | TextEditConfigColumnConfig<T, K> | NumberEditConfigColumnConfig<T, K> | SelectEditConfigColumnConfig<T, K> | MultiselectEditConfigColumnConfig<T, K> | BooleanEditConfigColumnConfig<T, K> | TextEditableColumnConfig<T, K> | SelectEditableColumnConfig<T, K> | MultiselectEditableColumnConfig<T, K>;
+type ColumnConfig<T, K extends keyof T> = ReadOnlyColumnConfig<T, K> | TextEditConfigColumnConfig<T, K> | NumberEditConfigColumnConfig<T, K> | SelectEditConfigColumnConfig<T, K> | SelectAsyncEditConfigColumnConfig<T, K> | MultiselectEditConfigColumnConfig<T, K> | MultiselectAsyncEditConfigColumnConfig<T, K> | BooleanEditConfigColumnConfig<T, K>;
 /**
  * Factory function to create column helper function for defining Table columns.
  *
@@ -214,8 +169,8 @@ type ColumnConfig<T, K extends keyof T> = ReadOnlyColumnConfig<T, K> | TextEditC
  *   headerLabel: "Status",
  *   editConfig: {
  *     mode: "select",
- *     options: [{ value: "active", label: "Active" }],
- *     onChange: (value, rowId) => save(value, rowId)
+ *     options: [{ id: "active", label: "Active" }],
+ *     onChange: (option, rowId) => save(option?.id, rowId)
  *   }
  * });
  *
@@ -224,8 +179,8 @@ type ColumnConfig<T, K extends keyof T> = ReadOnlyColumnConfig<T, K> | TextEditC
  *   headerLabel: "Tags",
  *   editConfig: {
  *     mode: "multiselect",
- *     options: [{ value: "urgent", label: "Urgent" }],
- *     onChange: (value, rowId) => save(value, rowId)
+ *     options: [{ id: "urgent", label: "Urgent" }],
+ *     onChange: (options, rowId) => save(options.map(o => o.id), rowId)
  *   }
  * });
  * ```