UNPKG

@grapecity/activereports

Version:

ActiveReportsJS

901 lines (898 loc) 23.7 kB
/** @module ReportDesigner */ /** */ import { Event, Rdl, ResourceLocator } from '@grapecity/ar-js-pagereport'; /** Represents toolbar buttons actions and hotkeys action handlers */ interface ActionHandlers { /** * Called on saving report. * @param options Current report info. * @returns Promise with new report info if report was saved or 'undefined' if operation was cancelled. */ onSave?(options: SaveReportInfo): Promise<SaveResult | undefined>; /** * Called on saving report as new. * @param options Current report info. * @returns Promise with new report info if report was saved or 'undefined' if operation was cancelled. */ onSaveAs?(options: SaveNewReportInfo): Promise<SaveAsResult | undefined>; /** * Called on opening report. * @returns Promise with report info or 'undefined' if operation was cancelled. */ onOpen?(): Promise<Report | undefined>; /** * Called on open report. * @returns Promise with report info or 'undefined' if operation was cancelled. */ onCreate?(): Promise<Report | NewReport | undefined>; /** * Called on render current report. * @param report Current report info. * @param resourceLocator ResourceLocator instance. * @param uiTheme Current UI theme. */ onRender?(report: ReportDefinition, resourceLocator?: Partial<ResourceLocator>, uiTheme?: UITheme): Promise<void>; /** * Called on open custom file menu. */ onOpenFileMenu?(): void; } type BuiltInColorTheme = Exclude<BuiltInUITheme, 'System' | 'ActiveReports' | 'ActiveReportsDark'>; /** * UI theme */ type BuiltInUITheme = 'System' | 'Default' | 'DefaultDark' | 'DarkOled' | 'HighContrast' | 'HighContrastDark' | 'ActiveReports' | 'ActiveReportsDark'; type ColorTheme = { name: string; type: ColorThemeType; backgroundMain: string; backgroundPanels: string; primary?: ColorThemeItem; secondary?: ColorThemeItem; neutral?: ColorThemeItem; error?: ColorThemeItem; warning?: ColorThemeItem; fontFamily?: string; }; type ColorThemeItem = string | ColorThemeShades; /** Contains built-in UI color themes. */ declare const ColorThemes: Record<BuiltInColorTheme, ColorTheme>; type ColorThemeShades = { veryLight: string; light: string; lighter: string; lightMedium: string; medium: string; base: string; darkMedium: string; darker: string; dark: string; veryDark: string; }; type ColorThemeType = 'light' | 'dark'; type CustomInitTemplates = { imperialTemplates?: Report[]; metricTemplates?: Report[]; }; /** Defines a dataset template for data panel. */ type DataSetTemplate = { /** Template ID */ id: string; /** Title */ title: string; /** Instructs designer to show edit dialog */ shouldEdit?: boolean; /** Instructs if DataSet, created from template, can be edited */ canEdit?: boolean; /** RDLX definition of DataSet */ template: Rdl.DataSet; /** RDLX definitions for nested DataSets */ nestedTemplates?: Rdl.DataSet[]; }; /** Defines the datasource template for data panel. */ type DataSourceTemplate = { /** Template ID */ id: string; /** Title */ title: string; /** Instructs designer to show edit dialog */ shouldEdit?: boolean; /** Instructs if DataSet, created from template, can be edited */ canEdit?: boolean; /** RDLX definition of DataSource */ template: Rdl.DataSource; /** DataSet templates for DataSource based on template */ datasets?: DataSetTemplate[]; }; /** Report designer component. */ declare class Designer { private impl; private events; /** * Creates report designer component instance. * @param element Component host element. * @param config Designer settings. */ constructor(element: string | Element | object, config?: DesignerConfig); /** * Creates report. * @param reportInfo Report info to load. * @param whenDirty Action to perform in case of 'dirty' report. */ createReport(reportInfo: NewReportInfo, whenDirty?: WhenDirty): Promise<void>; /** * Sets report. * @param report Report info to load. * @param whenDirty Action to perform in case of 'dirty' report. * @param isDirtyInitial Initial value for 'dirty' state after load. */ setReport(report: Report, whenDirty?: WhenDirty, isDirtyInitial?: boolean): Promise<void>; /** Gets current report. */ getReport(): Promise<ReportInfo>; /** * Sets actions handlers. * @param actions Actions handlers. */ setActionHandlers(actionHandlers: ActionHandlers): Promise<void>; /** * Sets resource provider. * @param resourceProvider Resources provider. */ setResourceProvider(resourceProvider: Partial<ResourceProvider>): Promise<void>; /** * Process command. * @param cmd Command name. */ processCommand(cmd: DesignerCommand): Promise<void>; /** * Sets DataSource templates * @param templates List of DataSource templates */ setDataSourceTemplates(templates: DataSourceTemplate[]): Promise<void>; /** * Sets component control items. For internal use only. * @hidden */ setControlItems(items: DesignerAppBarControlItem[]): void; /** * Gets component control items. For internal use only. * @hidden */ getControlItems(): Promise<DesignerAppBarControlItem[]>; /** * Open stylesheet editor. For internal use only. * @hidden */ openStylesheetEditor(stylesheetEditorProps: StylesheetEditorProps): void; get documentChanged(): Event<DocumentChangedEventArgs>; /** @hidden */ get themeChanged(): Event<Record<string, unknown>>; /** * Returns focus to Designer. */ focus(): void; /** * Gets API to manipulate designer. */ getEditorAPI(): Promise<EditorAPI>; /** * Access to the menu and sidebar panels */ getPanelsAPI(): Promise<PanelsAPI>; /** * Manipulate notifications panel. */ getNotificationsAPI(): Promise<NotificationsAPI>; /** * Gets list of available ReportParts libraries. */ getReportPartsLibraries(): Promise<ReportPartsLibrary[]>; /** * Sets list of available ReportParts libraries. */ setReportPartsLibraries(libraries: ReportPartsLibrary[]): Promise<void>; /** * Sets Master Report. */ setMasterReport(masterReportId: string): Promise<void>; } type DesignerAppBarControlItem = { type: 'about' | 'button'; id?: string; icon?: { type: 'svg'; /** JSX.Element content */ content: unknown; }; title?: string; disabled?: boolean; customCSS?: string; badge?: { content?: string; level?: 'warning' | 'error'; position?: string; rounded?: boolean; customCSS?: string; }; onClick?: (e: MouseEvent) => void; }; /** Command name. */ type DesignerCommand = 'save' | 'saveAs' | 'create' | 'open' | 'render'; /** Designer configuration */ type DesignerConfig = { /** * Application language, for example 'en', 'ja or 'zh'. * @default 'en' */ language?: string; /** If set to 'true' disables default open and save report hotkeys, */ disableOpenSaveHotkeys?: boolean; /** If set to 'true' disables default undo and redo report hotkeys. */ disableHistoryHotkeys?: boolean; /** Templates with default values for report and report items. */ customInitTemplates?: CustomInitTemplates; /** Settings for Report Parts library. */ reportPartsLibraries?: ReportPartsLibrary[]; /** * Sets available set of fonts. */ fontSet?: FontSet; /** * Specifies the default measurement units * @default 'in' */ units?: 'in' | 'cm'; /** * Configures various theme-related settings. */ themeConfig?: { /** * The initial theme to be applied. * * @default "Default" */ initialTheme?: string; /** * Controls Theme Picker behavior */ themeSelector?: { /** * An array of available themes that can be picked by the user. * These themes are built-in themes. * * @default ["System", "Default", "DefaultDark", "DarkOled", "HighContrast", "HighContrastDark", "ActiveReports", "ActiveReportsDark"] */ availableThemes?: UITheme[]; /** shows Theme Picker in UI */ isEnabled?: boolean; }; }; /** * Specifies the list of supported date formats */ dateFormats?: string[]; /** * When **lockLayout** is enabled, it is only possible to modify properties of existing report items.\ * I.e., adding a new report item or deleting of an existing one is not possible as well as other operations that modify report layout structure.\ * @default false */ lockLayout?: boolean; /** * When **storeUserPreferences** is **enabled**, user preferences will be saved to a browser storage.\ * In case **storeUnsavedReport** is **disabled**, the aforementioned functionality is not available * @default true */ storeUserPreferences?: boolean; /** * By default, focused elements (like buttons) are highlighted only for a small period of time after **Tab** key was pressed.\ * This settings makes focused elements permanently highlighted. * @default false */ disableFocusTimer?: boolean; /** * Disable usage of system clipboard. Copy-paste between designer instances will work only in the same browser in the same domain * @default false */ disableSystemClipboard?: boolean; /** * Return filtered array of descriptors in the order in which descriptors should be rearranged */ filterProperties?: (descriptors: PropertyDescriptor[], item: Record<string, any>) => PropertyDescriptor[]; /** Editor settings */ editor?: { /** Rulers settings */ rulers?: { /** Specifies whether **Rulers** needs to be shown by default */ visible?: boolean; /** Specifies a snapStep value. By default snapStep = { in: 0.25, cm: 0.5 } */ snapStep?: { in: number; cm: number; }; }; /** Specifies default grid size. If units = 'cm', value = 0.5cm by default. Else, value = 0,25in by default */ gridSize?: string; /** Specifies if grid must be shown or hidden by default */ showGrid?: boolean; /** * Specifies default value for the snapToGrid option * @default false */ snapToGrid?: boolean; /** * Specifies default value for the snapToGuides option * @default false */ snapToGuides?: boolean; }; /** **App Bar** settings */ appBar?: { /** * Specifies whether **App Bar** needs to be shown\ * @default true */ visible?: boolean; /** **Home** tab settings */ homeTab?: { /** * Specifies whether **Home** tab needs to be shown in Designer application bar. * @default true */ visible?: boolean; }; /** **Context Actions** tab settings */ contextActionsTab?: { /** * Specifies whether **Context Actions** tab needs to be shown in Designer application bar. * @default true */ visible?: boolean; }; /** **Parameters** tab settings */ parametersTab?: { /** * Specifies whether **Parameters** tab needs to be shown in Designer application bar for rdlx documents. * @default true */ visible?: boolean; }; /** **About** button settings */ aboutButton?: { /** * Specifies whether **About** button needs to be shown in Designer application bar. * @default true */ visible?: boolean; }; }; /** Tool Bar settings */ toolBar?: { /** * Specifies whether **Tool Bar** needs to be shown * @default true */ visible?: boolean; }; /** **Menu** settings */ menu?: { /** * Specifies whether **Main Menu** needs to be shown * @default true */ visible?: boolean; /** **Tool Box** settings */ toolBox?: { /** * Specifies whether left-side menu **Tool Box** needs to be shown * @default true */ visible?: boolean; }; /** **Document Explorer** settings */ documentExplorer?: { /** * Specifies whether **Document Explorer** button needs to be shown * @default true */ visible?: boolean; }; /** **Group Editor** settings */ groupEditor?: { /** * Specifies whether **Group Editor** button needs to be shown. * @default true */ visible?: boolean; }; /** **Layer Editor** settings */ layerEditor?: { /** * Specifies whether **Layer Editor** button needs to be shown. * @default true */ visible?: boolean; }; /** **Logo** settings */ logo?: { /** * Specifies whether logo needs to be shown in the menu * @default true */ visible?: boolean; /** * Sets a custom logo to be shown in the menu */ custom?: MenuIcon; }; }; /** Status Bar settings */ statusBar?: { /** * Specifies whether **Status Bar** needs to be shown * @default true */ visible?: boolean; toggleUnitsButton?: { /** * Specifies whether **Units Button** button needs to be shown * @default true */ visible?: boolean; }; toggleGridButton?: { /** * Specifies whether **Show Grid** toggle needs to be shown * @default true */ visible?: boolean; }; gridSizeEditor?: { /** * Specifies whether **Grid Size** editor needs to be shown * @default true */ visible?: boolean; }; rulersButton?: { /** * Specifies whether **Show Rulers** toggle needs to be shown * @default true */ visible?: boolean; }; propertiesModeButton?: { /** * @default true */ visible?: boolean; }; }; /** Property Grid settings */ propertyGrid?: { propertiesTab?: { /** * Specifies whether **Properties** tab needs to be shown * @default true */ visible?: boolean; }; /** * Specifies default properties mode */ mode?: 'Basic' | 'Advanced'; collapsibleCategories?: { /** * When set to true, Property Grid categories become collapsible, and app memorizes categories expanded/collapsed states. * @default true */ enabled?: boolean; }; saveExpandEditorsState?: { /** * When set to true, app memorizes editors expanded/collapsed states. * @default true */ enabled?: boolean; }; }; /** **Data**-related settings */ data?: { dataTab?: { /** * @default true */ visible?: boolean; }; /** **Data Sources** section settings */ dataSources?: { /** * Specifies whether **Data Sources** section needs to be shown * @default true */ visible?: boolean; /** * Specifies whether it is possible to modify (including add/edit/remove) data sources * @default false */ canModify: boolean; }; dataSets?: { /** * Specifies whether **Data Sets** section needs to be shown.\ * @default true */ visible?: boolean; /** * Specifies whether it is possible to modify (including add/edit/remove) data sets.\ * @default false */ canModify: boolean; }; parameters?: { /** * Specifies whether **Parameters** section needs to be shown.\ * @default true */ visible?: boolean; /** * Specifies whether it is possible to modify (including add/edit/remove) report parameters.\ * @default true */ canModify: boolean; }; commonValues?: { /** * Specifies whether **Common Values** section needs to be shown.\ * @default true */ visible?: boolean; }; }; }; type DocumentChangedEventArgs = { /** RDLX report definition. */ definition: Rdl.Report; /** True if report is in dirty (not saved) state. */ isDirty: boolean; }; /** * Information about the availability of common actions with the report and selected items */ type EditorAPI = { /** Flag when the can undo */ canUndo: () => boolean; /** Flag when the can redo */ canRedo: () => boolean; /** Flag when you can cut the selected item/items */ canCut: () => boolean; /** Flag when you can paste the selected item/items */ canPaste: () => boolean; /** Flag when you can copy the selected item/items */ canCopy: () => boolean; /** Flag when you can delete the selected item/items */ canDelete: () => boolean; /** Action undo */ undo: () => void; /** Action redo */ redo: () => void; /** Action cut */ cut: () => void; /** Action copy */ copy: () => void; /** Action paste */ paste: () => void; /** Action delete */ delete: () => void; }; /** * Fonts set. * * ``` * default: predefined fonts * registered: fonts registered in FontStore * all: predefined an registered in FontStore fonts * ``` */ type FontSet = 'default' | 'registered' | 'all'; /** Represents image information. */ type ImageResourceInfo = { /** Resource ID. */ id: string; /** Resource display name. */ displayName?: string; /** Mime type. */ mimeType: string; /** Thumbnail. */ thumbnail?: string; }; type MenuCssIcon = { type: 'css'; class: string; }; type MenuIcon = MenuCssIcon; /** Report info representing new report to be created. */ type NewReport = { /** Report id. */ id?: string; /** Report display name. */ displayName?: string; /** Type of report. */ reportType: ReportType; /** Master report id. */ masterReportId?: string; }; /** New report info. */ type NewReportInfo = { /** Type of report. */ reportType: ReportType; /** Master report id. */ masterReportId?: string; }; type NotificationsAPI = { /** * Sends a notification of specified level, caption and content * @param level Notification level. Determines color and icons used for the notifications * @param caption Notification caption. Shown by default when notification pops up, then used as a title in Notification Details view * @param content Notification content. Only visible when Notification Details are open */ send: (level: 'info' | 'warning' | 'error', caption: string, content?: string) => void; /** * Sends a general notification. Can be used to notify when any user-initiated action is complete * @param caption Notification caption * @param text Optional notification content */ info: (caption: string, text?: string) => void; /** * Sends an error notification * @param caption Error caption * @param errorText Optional error details */ error: (caption: string, errorText?: string) => void; /** * Sends a warning notification * @param caption Warning caption * @param warningText Optional warning details */ warning: (caption: string, warningText?: string) => void; /** * Dismisses all the notifications */ dismissAll: () => void; }; /** Contains access to the menu and sidebar panels */ type PanelsAPI = { /** * Menu API * */ menu: { open: (id: string) => void; pin: () => void; close: () => void; }; /** * Sidebar API * */ sidebar: { open: (id: string) => void; close: () => void; }; }; type PropertyDescriptor = { /** Specifies grouping for the property */ category: string; /** Specifies label for the property */ label: string; /** Specifies type of the editor that will be rendered */ type: string; /** Path inside objectValue to the value of the property */ valuePath: string; /** Specifies in which view mode the editor should be visible */ mode: PropertyDisplayMode; }; type PropertyDisplayMode = 'simple' | 'advanced' | 'both'; /** Report info representing report by ID or definition */ type Report = ReportLink | ReportDefinition; /** Report info representing report by definition. */ type ReportDefinition = { /** Report id. */ id?: string; /** Report display name. */ displayName?: string; /** RDLX report definition. */ definition: Rdl.Report; }; /** Represents current report information. */ type ReportInfo = { /** Report id. */ id: string | null; /** Report display name. */ displayName: string; /** RDLX report definition. */ definition: Rdl.Report; /** True if report is in dirty (not saved) state. */ isDirty: boolean; }; /** Report info representing report by ID. */ type ReportLink = { /** Report ID */ id: string; /** Report display name. */ displayName?: string; }; type ReportPartsLibrary = { displayName?: string; name: string; id: string; }; /** Represents external resource information. */ type ReportResourceInfo = { /** Resource ID. */ id: string; /** Resource display name. */ displayName?: string; }; /** * Type of report * ``` * CPL - Continuous Page Layout * FPL - Fixed Page Layout * Pageless - Pageless Report Layout * ``` */ type ReportType = 'CPL' | 'FPL' | 'Pageless'; /** Represents external resources provider. */ interface ResourceProvider extends ResourceLocator { /** * Gets available reports list. * @returns List of available reports. */ getReportsList(): Promise<ReportResourceInfo[]>; /** * Gets available themes list. * @returns List of available themes. */ getThemesList(): Promise<ThemeResourceInfo[]>; /** * Gets available images list. * @returns List of available images. */ getImagesList(): Promise<ImageResourceInfo[]>; /** * Gets available master reports list. * @returns List of available master reports. */ getMasterReportList(): Promise<ReportResourceInfo[]>; /** * Gets available shared stylesheets list. * @returns List of available shared stylesheets. */ getStylesheetList(): Promise<StylesheetResourceInfo[]>; } /** Represents result of "save new report" operation. */ type SaveAsResult = { /** New report ID. */ id: string; /** Report display name. */ displayName?: string; }; /** Current report info to be saved as new one. */ type SaveNewReportInfo = { /** Current report ID. */ id?: string; /** Current report display name. */ displayName?: string; /** Current RDLX report definittion. */ definition: Rdl.Report; }; /** Current report info to be saved. */ type SaveReportInfo = { /** Current report ID. */ id: string; /** Current report display name. */ displayName?: string; /** Current RDLX report definittion. */ definition: Rdl.Report; }; /** Represents result of "save report" operation. */ type SaveResult = { /** Report display name after save. */ displayName?: string; }; type StylesheetEditorProps = { stylesheet?: Rdl.Stylesheet; }; /** Represents external stylesheet information. */ type StylesheetResourceInfo = { /** Resource ID. */ id: string; /** Stylesheet content. */ content: Rdl.Stylesheet; }; /** Report theme short representation. */ type ThemeInfo = { /** Dark1 theme color */ Dark1: string; /** Dark2 theme color */ Dark2: string; /** Light1 theme color */ Light1: string; /** Light2 theme color */ Light2: string; /** Accent1 theme color */ Accent1: string; /** Accent2 theme color */ Accent2: string; /** Accent3 theme color */ Accent3: string; /** Accent4 theme color */ Accent4: string; /** Accent5 theme color */ Accent5: string; /** Accent6 theme color */ Accent6: string; /** Major text theme font family */ MajorFontFamily: string; /** Minor text theme font family */ MinorFontFamily: string; }; /** Represents theme information. */ type ThemeResourceInfo = { /** Resource ID. */ id: string; /** Resource display name. */ displayName?: string; /** Theme short representation. */ info: ThemeInfo; }; type UITheme = BuiltInUITheme | ColorTheme; /** * Represents action to perform in case of dirty report. * * ``` * ask: show comfirmation dialog * override: override dirty report * throw: throw error * ``` */ type WhenDirty = 'ask' | 'override' | 'throw'; export { type ActionHandlers, type ColorTheme, type ColorThemeItem, type ColorThemeShades, type ColorThemeType, ColorThemes, type CustomInitTemplates, type DataSetTemplate, type DataSourceTemplate, Designer, type DesignerAppBarControlItem, type DesignerCommand, type DesignerConfig, type DocumentChangedEventArgs, type EditorAPI, type FontSet, type ImageResourceInfo, type MenuCssIcon, type MenuIcon, type NewReport, type NewReportInfo, type NotificationsAPI, type PanelsAPI, type PropertyDescriptor, type PropertyDisplayMode, type Report, type ReportDefinition, type ReportInfo, type ReportLink, type ReportResourceInfo, type ReportType, type ResourceProvider, type SaveAsResult, type SaveNewReportInfo, type SaveReportInfo, type SaveResult, type ThemeInfo, type ThemeResourceInfo, type WhenDirty, };