@progress/kendo-react-grid/toolbar-tools/smartbox/interfaces/SmartBoxTypes.d.ts

React Data Grid (Table) provides 100+ ready-to-use data grid features. KendoReact Grid package

/**
 * @license
 *-------------------------------------------------------------------------------------------
 * Copyright © 2026 Progress Software Corporation. All rights reserved.
 * Licensed under commercial license. See LICENSE.md in the package root for more information
 *-------------------------------------------------------------------------------------------
 */
import { CompositeFilterDescriptor } from '@progress/kendo-data-query';
import { SpeechToTextButtonProps } from '@progress/kendo-react-buttons';
import { GridToolbarAIAssistantRequestData } from '../../../index.js';
import { GridSmartBoxAIAssistantSearchProps, GridSmartBoxSearchProps } from './SearchTypes.js';
import { TextBoxProps } from '@progress/kendo-react-inputs';
import { GridSmartBoxHistoryProps } from './utilTypes.js';
import { AxiosRequestConfig } from 'axios';
/**
 * Represents the available modes for the SmartBox component.
 *
 * - `search` - Standard text search mode with filtering capabilities
 * - `semanticSearch` - AI-powered semantic search mode
 * - `aiAssistant` - AI assistant mode for natural language grid operations
 */
export type SmartBoxMode = 'search' | 'semanticSearch' | 'aiAssistant';
/**
 * Represents a history item stored in the SmartBox history.
 */
export interface HistoryItem {
    /**
     * The text content of the history item.
     */
    text: string;
    /**
     * The timestamp when the history item was created.
     */
    timestamp: Date;
    /**
     * Optional format string for displaying the timestamp.
     */
    format?: string;
}
/**
 * Represents the event data passed when an AI prompt request is initiated.
 */
export interface GridSmartBoxRequestEvent {
    /**
     * The request data containing prompt message, columns, and request options.
     */
    requestData: GridToolbarAIAssistantRequestData;
}
/**
 * Base interface for search events containing filter descriptor and search value.
 */
interface GridSmartBoxSearchBaseEvent extends CompositeFilterDescriptor {
    /**
     * The search value entered by the user.
     */
    searchValue: string;
}
/**
 * Represents the event data passed when a search is performed.
 */
export interface GridSmartBoxSearchEvent extends GridSmartBoxSearchBaseEvent {
    /**
     * Returns whether the default action has been prevented.
     *
     * @returns `true` if the default action was prevented, otherwise `false`.
     */
    isDefaultPrevented: () => boolean;
    /**
     * Prevents the default search action from being executed.
     * Use this to handle the search manually.
     */
    preventDefault: () => void;
}
/**
 * Represents the event data passed when an AI response is received successfully.
 */
export interface GridSmartBoxResponseSuccessEvent {
    /**
     * The response data from the AI service.
     */
    response: any;
}
/**
 * Represents the event data passed when an AI response returns an error.
 */
export interface GridSmartBoxResponseErrorEvent {
    /**
     * The error object or message from the failed AI request.
     */
    error: any;
}
/**
 * Configuration options for the semantic search mode.
 */
export interface GridSmartBoxSemanticSearchConfigProps {
    /**
     * Enables or disables the semantic search mode.
     */
    enabled?: boolean;
    /**
     * Sets the placeholder text for the semantic search input.
     */
    placeholder?: string;
    /**
     * Sets the debounce delay in milliseconds before triggering a semantic search.
     *
     * @default 500
     */
    delay?: number;
    /**
     * Configures the semantic search history settings.
     * Can be a boolean to enable/disable or an object with detailed settings.
     */
    history?: boolean | GridSmartBoxHistoryProps;
}
/**
 * Configuration options for the AI assistant mode.
 *
 * The AI assistant supports three operational modes:
 * - **Auto mode**: Set `requestOptions` (with `url` property) - SmartBox handles the request automatically
 * - **Controlled mode**: Set `requestUrl` without `requestOptions` - SmartBox makes requests but you control loading state
 * - **Manual mode**: Don't set `requestUrl` or `requestOptions` - Handle requests yourself via `onAIPromptRequest`
 */
export interface GridSmartBoxAIAssistantConfigProps {
    /**
     * Enables or disables the AI assistant mode.
     */
    enabled?: boolean;
    /**
     * Sets the placeholder text for the AI assistant input.
     */
    placeholder?: string;
    /**
     * Defines the URL to which the AI request will be sent.
     * When set without `requestOptions`, enables controlled mode.
     *
     * @example
     * ```tsx
     * // Controlled mode
     * <SmartBox aiAssistantConfig={{ requestUrl: 'https://api.example.com/ai/grid' }} />
     * ```
     */
    requestUrl?: string;
    /**
     * Defines the options for the axios request.
     * When set (with `url` property), enables auto mode where SmartBox handles requests automatically.
     *
     * @example
     * ```tsx
     * // Auto mode - SmartBox handles everything
     * <SmartBox aiAssistantConfig={{
     *   requestOptions: {
     *     url: 'https://api.example.com/ai/grid',
     *     timeout: 5000,
     *     headers: { 'Authorization': 'Bearer token' }
     *   }
     * }} />
     * ```
     */
    requestOptions?: AxiosRequestConfig;
    /**
     * List of suggested prompts to display in the popup.
     *
     * @example
     * ```tsx
     * <SmartBox aiAssistantConfig={{
     *   promptSuggestions: ['Sort by price', 'Filter active items', 'Group by category']
     * }} />
     * ```
     */
    promptSuggestions?: string[];
    /**
     * Enables the speech-to-text functionality.
     * Can be a boolean to enable/disable or an object with SpeechToTextButton props.
     */
    speechToTextButton?: boolean | SpeechToTextButtonProps;
    /**
     * Configures the AI assistant history settings.
     * Can be a boolean to enable/disable or an object with detailed settings.
     */
    history?: boolean | GridSmartBoxHistoryProps;
}
/**
 * Represents the props for the SmartBox component.
 * SmartBox provides a unified search interface with three modes: standard search,
 * semantic search, and AI assistant for natural language grid operations.
 *
 * The AI assistant supports three operational modes configured via `aiAssistantConfig`:
 * - **Auto mode**: Set `requestOptions` (with `url`) - SmartBox handles requests automatically
 * - **Controlled mode**: Set `requestUrl` - SmartBox makes requests, you control loading state
 * - **Manual mode**: Don't set `requestUrl` or `requestOptions` - Handle requests via `onAIPromptRequest`
 *
 * @example
 * ```tsx
 * // Auto mode - SmartBox handles everything automatically
 * <SmartBox
 *   aiAssistantConfig={{
 *     enabled: true,
 *     requestOptions: {
 *       url: '/api/ai/grid',
 *       timeout: 5000
 *     },
 *     promptSuggestions: ['Sort by price', 'Filter active items']
 *   }}
 *   searchConfig={{ enabled: true }}
 * />
 *
 * // Controlled mode - SmartBox makes requests, you control loading state
 * <SmartBox
 *   loading={isLoading}
 *   aiAssistantConfig={{
 *     enabled: true,
 *     requestUrl: '/api/ai/grid'
 *   }}
 *   onAIPromptRequest={(e) => setIsLoading(true)}
 *   onAIResponseSuccess={(e) => setIsLoading(false)}
 * />
 *
 * // Manual mode - fully custom request handling
 * <SmartBox
 *   loading={isLoading}
 *   aiAssistantConfig={{ enabled: true }}
 *   onAIPromptRequest={(e) => {
 *     setIsLoading(true);
 *     myCustomFetch(e.requestData).then(handleResponse);
 *   }}
 * />
 * ```
 */
export interface GridSmartBoxAIAssistantProps extends Omit<GridSmartBoxAIAssistantSearchProps, 'delay'> {
    /**
     * Configures the search mode settings.
     * Can be a boolean to enable/disable or an object with detailed settings.
     *
     * @example
     * ```tsx
     * <SmartBox searchConfig={{ enabled: true, fields: ['name', 'description'], delay: 300 }} />
     * ```
     */
    searchConfig?: boolean | GridSmartBoxSearchProps;
    /**
     * Configures the semantic search mode settings.
     * Can be a boolean to enable/disable or an object with detailed settings.
     *
     * @example
     * ```tsx
     * <SmartBox semanticSearchConfig={{ enabled: true, placeholder: 'Search with AI...' }} />
     * ```
     */
    semanticSearchConfig?: boolean | GridSmartBoxSemanticSearchConfigProps;
    /**
     * Configures the AI assistant mode settings.
     * Can be a boolean to enable/disable or an object with detailed settings.
     *
     * @example
     * ```tsx
     * <SmartBox aiAssistantConfig={{
     *   enabled: true,
     *   requestUrl: '/api/ai/grid',
     *   promptSuggestions: ['Sort by price', 'Filter active items']
     * }} />
     * ```
     */
    aiAssistantConfig?: boolean | GridSmartBoxAIAssistantConfigProps;
    /**
     * Sets the currently active mode.
     *
     * @example
     * ```tsx
     * <SmartBox activeMode="aiAssistant" />
     * ```
     */
    activeMode?: SmartBoxMode;
    /**
     * Sets the text direction.
     *
     * @default 'ltr'
     */
    dir?: 'ltr' | 'rtl';
    /**
     * Sets the size of the SmartBox.
     *
     * @default 'medium'
     *
     * @example
     * ```tsx
     * <SmartBox size="large" />
     * ```
     */
    size?: 'small' | 'medium' | 'large';
    /**
     * Sets whether the SmartBox is in loading state.
     * Use this for controlled mode to manage loading state externally.
     *
     * @example
     * ```tsx
     * <SmartBox loading={isLoading} onAIPromptRequest={() => setIsLoading(true)} />
     * ```
     */
    loading?: boolean;
    /**
     * Custom render function for prompt suggestions.
     *
     * @example
     * ```tsx
     * <SmartBox
     *   promptSuggestionRender={(suggestion, onClick) => (
     *     <li className="custom-suggestion" onClick={onClick}>{suggestion}</li>
     *   )}
     * />
     * ```
     */
    promptSuggestionRender?: (suggestion: string, onClick: () => void) => React.ReactNode;
    /**
     * Custom render function for history items.
     *
     * @example
     * ```tsx
     * <SmartBox
     *   historyItemRender={(item, onClick) => (
     *     <li className="custom-history" onClick={onClick}>
     *       {item.text} - {item.timestamp.toLocaleString()}
     *     </li>
     *   )}
     * />
     * ```
     */
    historyItemRender?: (item: HistoryItem, onClick: () => void) => React.ReactNode;
    /**
     * Props to pass to the TextBox component.
     */
    textboxProps?: TextBoxProps;
    /**
     * Fires when the SmartBox popup opens.
     *
     * @example
     * ```tsx
     * <SmartBox onOpen={() => console.log('Popup opened')} />
     * ```
     */
    onOpen?: () => void;
    /**
     * Fires when the SmartBox popup closes.
     *
     * @example
     * ```tsx
     * <SmartBox onClose={() => console.log('Popup closed')} />
     * ```
     */
    onClose?: () => void;
    /**
     * Fires when the SmartBox input is focused.
     */
    onFocus?: () => void;
    /**
     * Fires when the SmartBox input is blurred.
     */
    onBlur?: () => void;
    /**
     * Fires when a search is performed in Search mode.
     * The event contains the search value and filter descriptor.
     *
     * @example
     * ```tsx
     * <SmartBox
     *   onSearch={(event) => {
     *     console.log('Search value:', event.searchValue);
     *     // Prevent default filtering if needed
     *     event.preventDefault();
     *   }}
     * />
     * ```
     */
    onSearch?: (event: GridSmartBoxSearchEvent) => void;
    /**
     * Fires when a search is performed in Semantic Search mode.
     * The event contains the search value and filter descriptor.
     *
     * @example
     * ```tsx
     * <SmartBox
     *   onSemanticSearch={(event) => {
     *     console.log('Semantic search:', event.searchValue);
     *   }}
     * />
     * ```
     */
    onSemanticSearch?: (event: GridSmartBoxSearchEvent) => void;
    /**
     * Fires when an AI prompt request is initiated.
     * Use this callback to intercept requests, modify data, or handle requests manually.
     *
     * @example
     * ```tsx
     * // Controlled mode - intercept and modify request
     * <SmartBox
     *   onAIPromptRequest={(event) => {
     *     console.log('Prompt:', event.requestData.promptMessage);
     *     setLoading(true);
     *   }}
     * />
     *
     * // Manual mode - handle request yourself
     * <SmartBox
     *   onAIPromptRequest={(event) => {
     *     fetch('/api/ai', {
     *       method: 'POST',
     *       body: JSON.stringify(event.requestData)
     *     }).then(handleResponse);
     *   }}
     * />
     * ```
     */
    onAIPromptRequest?: (event: GridSmartBoxRequestEvent) => void;
    /**
     * Fires when an AI response is received successfully.
     * Only fires in auto or controlled mode when a `requestUrl` is configured.
     *
     * @example
     * ```tsx
     * <SmartBox
     *   onAIResponseSuccess={(event) => {
     *     console.log('AI response:', event.response);
     *     setLoading(false);
     *   }}
     * />
     * ```
     */
    onAIResponseSuccess?: (event: GridSmartBoxResponseSuccessEvent) => void;
    /**
     * Fires when an AI response returns an error.
     * Only fires in auto or controlled mode when a `requestUrl` is configured.
     *
     * @example
     * ```tsx
     * <SmartBox
     *   onAIResponseError={(event) => {
     *     console.error('AI error:', event.error);
     *     setLoading(false);
     *   }}
     * />
     * ```
     */
    onAIResponseError?: (event: GridSmartBoxResponseErrorEvent) => void;
    /**
     * Fires when an AI request is cancelled by the user.
     * The user can cancel by clicking the stop button during loading.
     *
     * @example
     * ```tsx
     * <SmartBox
     *   onAICancelRequest={() => {
     *     console.log('Request cancelled');
     *     setLoading(false);
     *   }}
     * />
     * ```
     */
    onAICancelRequest?: () => void;
}
export {};