@sassoftware/vi-api/component/bindings.d.ts

Types used in the SAS Visual Investigator API

/**
 *
 * ******************************* BE AWARE !!!! *******************************
 *
 * Editing the bindings in this file will change the API the consumers are using.
 * Changing existing settings e.g. renaming input / output bindings or changing their types may cause breaking changes for existing consumers.
 * Adding new optional bindings is generally safe, but consider whether a new API should be created if the new bindings are not related to existing ones.
 *
 * If you need to make a breaking change, please coordinate with your team and update the version number in api/package.json accordingly.
 * If you need to add a new interface, please consider whether it can extend an existing one or if a new base interface should be created to group related bindings together.
 * Please also add JSDoc comments to the new bindings and interfaces to explain their purpose and usage.
 */
import { PageDataChange, PageDataChangeWithPageModel, PageModeChange, PageModeChangeWithPageModel } from "../control/events";
import { Relationship } from "../svi-datahub";
import { QueryMode } from "../svi-sand";
import { APISelectedItem, ControlContainer, CreateDialogResponse, IRelationshipWithLabel, RelationshipInformation, VIObject } from "../object/object-api";
import { PageModel, PageModelObjectData } from "../page-model/page-model-api";
import { LinkStatusResult, SearchObject, SearchQuery } from "../search/client/client-search-api";
import { HandleType, MinMaxDates, TimeSliderContextMenuHideOptions, TimeSliderEventDates, TimeSliderRange, TimeSliderRangeChangedEvent } from "../time-slider";
import { PageModeEvent } from "../control";
export interface SearchAndSelectWithPreviewInputBindings {
    initialQuery?: string;
    additionalModes?: QueryMode[];
    objectTypeFilter?: string[];
}
export interface SearchAndSelectWithPreviewBindings extends SearchAndSelectWithPreviewInputBindings {
    onSearchItemSelected: (selectedItem: SearchObject | null) => void;
    onSearchItemDoubleClicked?: (selectedItem: SearchObject) => void;
}
export interface PageViewerApi {
    save: () => Promise<void>;
    isDirty: () => boolean;
    isValid: () => Promise<boolean>;
    getPageModel: () => PageModel | undefined;
}
export type PageViewerBindings = CreateObjectPageBindings | EditObjectPageBindings | ViewObjectPageBindings | StaticDataPageBindings | PageBindings;
export declare enum PageViewerBindingsType {
    CreateObject = "CREATE",
    EditObject = "EDIT",
    ViewObject = "VIEW",
    StaticData = "STATIC"
}
/**
 * Component bindings to configure a page viewer for creating a new object.
 */
export interface CreateObjectPageBindings extends CommonPageViewerBindings {
    bindingsType: PageViewerBindingsType.CreateObject;
    /** Page context to use. */
    eventName: PageModeEvent.CREATE;
    /** Entity type of the object. */
    docType: string;
    /** Temporary ID to use for the unsaved object. */
    tempCreateId?: string;
    /** Initial values to populate the pageModel data. */
    initialCreateData?: Record<string, any>;
    /**
     * Optionally provide a pageModel using window.sas.vi.pageModel.createFromObject.
     * The pageModel type must match docType.
     * The pageModel data will be populated with initialCreateData.
     * The pageModel can be used to inspect current data and validity,
     * but the reference to this model will be broken if a new template is loaded due to a mode transition or other condition.
     * Prefer using setApi and onChange to interact with the page.
     */
    pageModel?: PageModel;
}
/**
 * Component bindings to configure a page viewer for editing an existing object.
 */
export interface EditObjectPageBindings extends CommonPageViewerBindings {
    bindingsType: PageViewerBindingsType.EditObject;
    /** Page context to use. */
    eventName: PageModeEvent.EDIT;
    /** Entity type of the object. */
    docType: string;
    /** Object ID */
    docId: string;
    /** Use the given page template by UUID regardless of page context. */
    templateUuid?: string;
    /**
     * Optionally provide a pageModel using window.sas.vi.pageModel.createFromObject.
     * The pageModel type must match `docType`.
     * The `docType` and `docId` are used to fetch the document page, and `pageModel.data` is set using the field values from this response.
     * The pageModel can be used to inspect current data and validity,
     * but the reference to this model will be broken if a new template is loaded due to a mode transition or other condition.
     * Prefer using `setApi` and `onChange` to interact with the page.
     */
    pageModel?: PageModel;
}
/**
 * Component bindings to configure a page viewer for a read-only view of an existing object.
 */
export interface ViewObjectPageBindings extends CommonPageViewerBindings {
    bindingsType: PageViewerBindingsType.ViewObject;
    /** Page context to use. */
    eventName: PageModeEvent.OPEN | PageModeEvent.INSPECT | PageModeEvent.SUMMARY;
    /** Entity type of the object. */
    docType: string;
    /** Object ID */
    docId: string;
    /** Use the given page template by UUID regardless of page context. */
    templateUuid?: string;
}
/**
 * Component bindings to configure a page viewer for a read-only view of static object data.
 */
export interface StaticDataPageBindings extends CommonPageViewerBindings {
    bindingsType: PageViewerBindingsType.StaticData;
    /** Object data to create the page response. */
    staticDocumentData: VIObject;
}
export interface CommonPageViewerBindings {
    /** Show the page toolbar. This contains the toolbar actions associated with the object's entity type. */
    showToolbar?: boolean;
    /**
     * Assign the given CSS classes to the page viewer's container.
     * This element encompasses the main document view and the toolbar.
     */
    containerClass?: string;
    /** If true, the page viewer will fill its parent element's height. */
    fitToContainerHeight?: boolean;
    /**
     * Assign the given CSS classes to the page viewer's main section.
     * This element displays the main document, excluding toolbar.
     */
    pageClass?: string;
    /**
     * Enable the workspace and insight tabs to be rendered.
     */
    enableSheets?: boolean;
    /**
     * A callback that is called when the page viewer is initialized.
     * It provides an API that can be used to check the page viewer state and save the document.
     */
    setApi?: (api: PageViewerApi) => void;
    /** A callback that is called when the page viewer dirty state changes. */
    onDirty?: (isDirty: boolean) => void;
    /** A callback that is called when the pageModel's mode or data changes. */
    onChange?: (change: PageDataChange | PageModeChange | PageDataChangeWithPageModel | PageModeChangeWithPageModel) => void;
}
/** @deprecated use {@link PageViewerBindings} */
export interface PageBindings {
    bindingsType?: never;
    docId?: string;
    docType?: string;
    eventName?: string;
    templateUuid?: string;
    showToolbar?: boolean;
    tempCreateId?: string;
    containerClass?: string;
    fitToContainerHeight?: boolean;
    pageClass?: string;
    enableSheets?: string;
    pageModel?: PageModel;
    staticDocumentData?: Record<string, any>;
    initialCreateData?: Record<string, any>;
    setApi?: (api: PageViewerApi) => void;
    mainTab?: string;
    onDirty?: (isDirty: boolean) => void;
    onChange?: (change: PageDataChange | PageModeChange | PageDataChangeWithPageModel | PageModeChangeWithPageModel) => void;
}
export interface PagePreviewBindings {
    templateUuid: string;
}
export interface ControlCollectionBindings {
    controlContainer?: ControlContainer;
    pageModel?: PageModel;
    root?: boolean;
}
/**
 * Defines the bindings for managing relationship details in a component.
 */
export interface RelationshipDetailsInputBindings {
    /**
     * Defines the identifier of the target object type that the relationship references.
     */
    targetObjectTypeName: string;
    /**
     * Defines the display label of the target object type.
     */
    targetObjectTypeLabel: string;
    /**
     * Defines the identifier of the parent object type that owns the relationship.
     */
    parentObjectTypeName: string;
    /**
     * Specifies the user-friendly label of the parent object type.
     */
    parentObjectTypeLabel: string;
    /**
     * Represents the list of reasons that define the purpose or context of the relationship.
     */
    linkReasons: Relationship[] | IRelationshipWithLabel[];
    /**
     * Represents the currently selected item in the relationship, if applicable.
     * Contains an object with `id`, `type`, and optional `title` fields to identify the selected item.
     */
    selectedItem?: APISelectedItem;
    /**
     * Represents the list of currently selected items in the relationship, if applicable.
     */
    selectedItems?: APISelectedItem[];
    /**
     * Fields that are read-only and cannot be modified by the user within the relationships properties panel
     */
    readOnlyFields?: string[];
    /**
     * Fields that are hidden and cannot be seen by the user within the relationships properties panel
     */
    hiddenFields?: string[];
    /**
     * Contains the data for a new page model, if applicable.
     * Includes a `PageModel` or `PageModelObjectData` object to represent the model structure.
     */
    newPageModel?: {
        model: PageModel | PageModelObjectData;
    };
    /**
     * Indicates whether to display the page viewer component. Default: true
     */
    showPageViewer?: boolean;
    /**
     * Used to show link status in the relationship properties component when coming from the relate to button bulk link flow
     */
    linkStatusResults?: LinkStatusResult[];
    /**
     * Used to show link status in the relationship properties component when coming from the relate to button bulk link flow
     */
    originalWizardResults?: CreateDialogResponse[];
    /**
     * Represents the current field values of the relationship as key-value pairs.
     */
    relationshipValues?: Record<string, unknown>;
    /**
     * Represents the initial field values used to populate the related object during creation.
     */
    initialCreateData?: Record<string, unknown>;
    /**
     * Entity names of the selected items.
     */
    entityNames?: string[];
    /**
     * Entity name of the parent object to which we are relating.
     */
    relateToParentName?: string;
    /**
     * Stored relationship info for each selected item, used to restore state when navigating between wizard steps.
     */
    storedAllRelationshipInfo?: Map<string, RelationshipInformation>;
}
export interface RelationshipDetailsBindings extends RelationshipDetailsInputBindings {
    /**
     * Callback invoked when a link reason is selected.
     * @param linkReason - The selected link reason.
     */
    onLinkReasonSelected: (linkReason: Relationship | IRelationshipWithLabel | undefined) => void;
    /**
     * Callback to set the API for the page viewer.
     * Provides a `PageViewerAPI` instance to the component.
     * @param api - The `PageViewerAPI` instance.
     */
    setApi?: (api: PageViewerApi) => void;
    /**
     * Callback invoked when the related page changes.
     * Triggered by events such as data updates or mode transitions.
     * @param change - The event describing the change, either `PageDataChange`, `PageModeChange`, `PageDataChangeWithPageModel`, or `PageModeChangeWithPageModel`.
     */
    onRelatedPageChange?: (change: PageDataChange | PageModeChange | PageDataChangeWithPageModel | PageModeChangeWithPageModel) => void;
    /**
     * Callback invoked when the relationship values are updated.
     * Provides both the current and previous values for comparison.
     * @param event - Object containing current and previous relationship values.
     */
    onRelationshipValuesChange?: (event: {
        current: Record<string, any>;
        previous?: Record<string, any>;
    }) => void;
    /**
     * Callback invoked when the related page loading is complete.
     */
    onRelatedPageLoad?: () => void;
    /**
     * Callback invoked when the relationship information is updated.
     * @param allRelationshipInfo - Map of all relationship information keyed by item ID.
     */
    onAllRelationshipInfoChanged?: (allRelationshipInfo: Map<string, RelationshipInformation>) => void;
    /**
     * Callback invoked when the selected items are updated.
     * @param event - Object containing the updated selected items and optionally the removed item.
     */
    selectedItemsUpdated?: (event: {
        selectedItems: APISelectedItem[] | undefined;
        removedItem?: APISelectedItem;
        removedItemIndex?: number;
    }) => void;
}
export interface SearchInputInputBindings {
    entityName: string;
    queryBuilderId?: string;
    showQueryBuilder?: boolean;
    queryText?: string;
    autoFocus?: boolean;
    queryBuilderOkButtonLabel?: string;
    queryModel?: QueryBuilderModel;
    performSearch?: boolean;
}
export interface QueryBuilderModel {
    manualQueryString?: string;
    model: QueryBuilderEntityModel[];
}
export interface QueryBuilderEntityModel {
    entity: string;
    queries: QueryBuilderItem[];
    singleChildSearch?: boolean;
}
export interface QueryBuilderItem {
    booleanValue?: boolean | string;
    boost?: number;
    dateTimeValue?: string | Date;
    dateValue?: string | Date;
    exclude?: boolean;
    field?: string;
    fromDateTimeValue?: string | Date;
    fromDateValue?: string | Date;
    fromNumericValue?: number;
    numericValue?: number;
    operator?: string;
    phonetic?: boolean;
    previousField?: string;
    proximity?: number;
    rangeValidationError?: boolean;
    referenceValue?: string;
    relationshipField?: boolean;
    relationshipTypeValue?: string;
    relativeDateDatetimeNumericValue?: number;
    relativeDateDatetimeUnitsValue?: string;
    stringValidationError?: boolean;
    synonym?: boolean;
    textValue?: string;
    toDateTimeValue?: string | Date;
    toDateValue?: string | Date;
    toNumericValue?: number;
    userGroupValue?: Array<{
        id: string;
        type: string;
    }>;
}
export interface SearchInputBindings extends SearchInputInputBindings {
    onSearch?: (model: SearchQuery) => void;
    onValueChange?: (val: string) => void;
}
export interface TimeSliderInputBindings {
    timeSliderId: string;
    timeSliderDates: TimeSliderEventDates;
    viewRange: TimeSliderRange;
    handleType?: HandleType;
    isReadOnly?: boolean;
    sliderWidth?: number;
    disableSwitchHandleType?: boolean;
    contextMenuHideOptions: TimeSliderContextMenuHideOptions;
    minMaxDates?: MinMaxDates;
}
export interface TimeSliderBindings extends TimeSliderInputBindings {
    rangeChangeEvent?: (rangeChangedEvent: TimeSliderRangeChangedEvent) => void;
    handleTypeChange?: (handleType: HandleType) => void;
    onLoad?: () => void;
    close?: () => void;
}
export type SviComponentBindings = ControlCollectionBindings | RelationshipDetailsBindings | SearchInputBindings | PageViewerBindings | PagePreviewBindings | SearchAndSelectWithPreviewBindings | TimeSliderBindings;
/**
 * Merges provided bindings with default bindings. If both are functions, wraps them so both are called.
 * @param provided The provided bindings.
 * @param defaults The default bindings.
 * @returns The merged bindings object.
 */
export declare function mergeBindings<T extends object>(provided?: T, defaults?: Partial<T>): T;