import type { SymbolInputProps } from "@vertigis/react-ui/SymbolInput"; import type { JSONSchema7 } from "json-schema"; import type * as Translate from "../region"; import type { ConfigurableItemKey } from "./ConfigurableItemKey"; import type { ActionContextType } from "./commands/ActionContextType"; import type { ReportTemplate, WorkflowTemplate } from "./commands/Templates"; /** * A translatable string, either a language string or a language string with * arguments to pass into it. */ export type TranslatableText = Translate.TranslatableText; /** * The scope of a search for a Portal query. */ export type SearchDomain = "global" | "org"; /** * The default type of command shown. */ export type ActionDefaultType = "command" | "workflow" | "report"; /** * The default type of operation shown. */ export type OperationDefaultType = "operation" | "workflow"; /** * Command setting modes. See `CommandSetting.mode`. */ export type CommandSettingMode = "all" | "workflow"; /** * Operation setting modes. See `OperationSetting.mode`. */ export type OperationSettingMode = "all"; /** * Type of result from a validation callback. */ export type ValidationResultType = "warning" | "error"; /** * The types of settings that a component's property can embody. * * @template T The type of settings values. */ export type Setting = ButtonSetting | CheckboxSetting | ColorSetting | CommandSetting | FileInputSetting | IconSetting | ImageSetting | IntegratedEditorSetting | LabelSetting | LinkSetting | ListSetting | MarkdownSetting | NumberInputSetting | OperationSetting | PinpointSetting | PasswordSetting | PortalItemInputSetting | PortalListSetting | SelectSetting | TagsSetting | TextInputSetting | ToggleSetting | SizingSetting | SymbolSetting; /** * An optionally collapsible group of related settings. */ export interface Group extends SettingBase { /** * @inheritdoc */ type: "group"; /** * If the empty string is provided then the group header will not be shown. */ displayName: string; /** * The settings to display in the group. */ settings: Setting[]; /** * If `true`, the user is able to collapse the group. */ collapsible?: boolean; /** * Whether the group is collapsed by default. Only applies if `collapsible` * is `true`. */ defaultCollapsed?: boolean; } /** * The schema that will help translate a component's settings into a * customizable form in VertiGIS Studio App Designer. */ export interface SettingsSchema { /** * The description of the component. * If one isn't provided, the * description from the Component or Service's manifest will be used. */ description?: string; /** * A URI to more information about the component. */ descriptionUri?: string | ((allSettingsValues: T) => string); /** * The display name to be used in the header of the component's settings. If * one isn't provided, the title from the Component or Service's manifest * will be used. */ displayName?: string | ((allSettingsValues: T) => string); /** * An additional description of the component. */ secondaryDescription?: Translate.TranslatableText; /** * The settings for the component. */ settings: (Setting | Group)[]; } /** * The basic, common properties shared by all Settings. */ export interface SettingBase { /** * The label for this setting. */ displayName: string; /** * The description of the setting. */ description?: string; /** * A uri to more information about the setting. */ descriptionUri?: string | ((allSettingsValues: T) => string); /** * Whether the entire schema should rerender when this setting changes. This * should only be used if the schema is unknown before this point, otherwise * isVisible should be used. */ refreshSchemaOnSettingChange?: boolean; /** * The visibility of the setting in the settings form. */ isVisible?: (allSettingsValues: T) => boolean; /** * Callback to update the settings. This can be used to update one property * in response to a different property changing. * * @param newSettingsValues The updated values from the callback function. * @param oldSettingsValues The old values from the before callback * function. */ onSubmitValue?: (newSettingsValues: T, oldSettingsValues: T) => Partial | Promise | undefined> | undefined; /** * An additional description of the component. */ secondaryDescription?: Translate.TranslatableText; } /** * Common interface for a setting that maps to a specific property in the * settings values. */ export interface IdentifiableSetting { /** * The ID of the setting. This needs to match the property name in `T` that * this setting controls. */ id: keyof T; } /** * A setting that has an optional isRequired property. */ export interface RequirableSetting { /** * Indicates whether the user must provide a value for this setting. */ isRequired?: boolean | ((allSettingsValues: T) => boolean); /** * The message to show to the user if a value is not provided for this * setting. */ requiredMessage?: string; } /** * A setting that has an optional isDisabled property. */ export interface DisableableSetting { /** * Indicates whether the setting is disabled. */ isDisabled?: boolean | ((allSettingsValues: T) => boolean); } /** * A setting that has an optional validate function property. */ export interface ValidatableSetting { /** * Validate the value of a setting. Can be useful when the validity of a * setting may depend on another setting's value. * * @param allValues The current settings values for all settings in this * schema. * @param value The value of this setting to validate. */ validate?: (allValues: T1, value: T2) => SettingValidationResultLike | Promise; } /** * A validatable setting that can return a result holding sub item validation * info. */ export interface ValidatableListSetting extends ValidatableSetting[]> { /** * Validate a setting and require the result to a * ListSettingValidationResult. */ validate?: (allValues: T1, value: ListItemSettings[]) => ListSettingValidationResult | Promise; } /** * The result of validating a single setting, which can be: * * - Undefined, validating the setting did not produce a warning or an error * - A string, which is considered to be an error message * - A SettingValidationResult, which can either be a warning or an error. */ export declare type SettingValidationResultLike = undefined | string | SettingValidationResult; /** * Base definition for the result produced from validating a single setting. */ export interface SettingValidationResult { /** * The type of result (e.g. error or warning). */ type: ValidationResultType; /** * The message to display to the user. */ message: string; } /** * Validation property representing validation of a list. */ export interface ListSettingValidationResult extends SettingValidationResult { /** * Validation results for each item in the list, keyed by item ID. */ items?: Record; } /** * A Setting type that allows a user to edit javascript / json within a Monaco * editor. */ export interface IntegratedEditorSetting extends SettingBase, IdentifiableSetting { /** * @inheritdoc */ type: "integratedEditor"; /** * The editor language. If the value is 'json', the value passed to this * setting should be a JSON object; if the value is 'javascript', the value * passed to this setting should be a string. */ editorLanguage: "json" | "javascript"; /** * The validation schema to use if the language is json. */ jsonSchema?: { /** * The JSON Schema (https://json-schema.org/). */ schema: JSONSchema7; /** * A unique identifier for the schema. */ uri: string; }; } /** * A Setting type that allows a user to configure a link to open Pinpoint with a * specific term. */ export interface PinpointSetting extends SettingBase, IdentifiableSetting { /** * @inheritdoc */ type: "pinpoint"; /** * The term to open pinpoint with. */ searchTerm: string; /** * The term to display. If not provided the search term will be displayed. */ title?: string; } /** * A Setting type that allows a user to configure a boolean property with a * checkbox. */ export interface CheckboxSetting extends SettingBase, IdentifiableSetting { /** * @inheritdoc */ type: "checkbox"; } /** * A Setting type that lets the user configure a symbol to populate a given * property. */ export interface SymbolSetting extends SettingBase, IdentifiableSetting, RequirableSetting { /** * @inheritdoc */ type: "symbol"; /** * Returns innerHTML for an SVG or a URL of an image to display as a preview * for the symbol. */ getPreview?: (data: SymbolInputProps["symbol"]) => string | Promise; } /** * A Setting type that lets the user select a color to populate a given * property. */ export interface ColorSetting extends SettingBase, IdentifiableSetting, RequirableSetting { /** * @inheritdoc */ type: "color"; } /** * An input type control that provides users to configure commands and command * arguments. */ export interface CommandSetting extends SettingBase, IdentifiableSetting, RequirableSetting { /** * @inheritdoc */ type: "command"; /** * The context of the command. */ contextType: ActionContextType; /** * The default tab shown when selecting a type of command. "command" and * "report" only applicable if `mode` is "all". */ defaultCommandType?: ActionDefaultType; /** * Only applicable for "workflow" command types. This specifies whether the * workflow's `target` property should be exposed and configurable. The * `target` property allows a workflow to specify where it should run in the * layout when activated. Default is true. */ enableWorkflowTarget?: boolean; /** * Whether the title and icon inputs should be hidden when the command is a * workflow. This is useful for menu items which already have a title and * icon input. These attributes are then copied down to the workflow. */ hideWorkflowTitleAndIcon?: boolean; /** * The mode of the command setting. If "all", commands, workflows, reports, * and the option to create new are all available. If "workflow", only the * option to choose or create a workflow are presented. Default is "all". */ mode?: CommandSettingMode; /** * Report templates associated with this command. These templates are shown * when the user creates a new report from this setting. */ reportTemplates?: ReportTemplate[]; /** * Workflow templates associated with this command. These templates are * shown when the user creates a new workflow from this setting. */ workflowTemplates?: WorkflowTemplate[]; } /** * An input type control that allows users to configure operations and operation * arguments. */ export interface OperationSetting extends SettingBase, IdentifiableSetting, RequirableSetting { /** * @inheritdoc */ type: "operation"; /** * The context of the operation. */ contextType: ActionContextType; /** * The default tab shown when selecting a type of operation. */ defaultOperationType?: OperationDefaultType; /** * Only applicable for "workflow" operation types. This specifies whether * the workflow's `target` property should be exposed and configurable. The * `target` property allows a workflow to specify where it should run in the * layout when activated. Default is true. */ enableWorkflowTarget?: boolean; /** * The mode of the operation setting. If "all", operations, workflows, and * the option to create new are all available. */ mode?: OperationSettingMode; /** * The expected output type of the operation. An operation is always * expected to return a value, so "none" is not an allowed context type for * this property. */ outputType?: ActionContextType; /** * Workflow templates associated with this operation. These templates are * shown when the user creates a new workflow from this setting. */ workflowTemplates?: WorkflowTemplate[]; } /** * An input type control that allows users to upload files. */ export interface FileInputSetting extends SettingBase, IdentifiableSetting, RequirableSetting, ValidatableSetting { /** * @inheritdoc */ type: "file"; /** * A list of valid 'accept' attribute values on the input element. */ accept?: string[]; /** * Whether the file should be added as a resource to the app. */ addResource?: boolean; /** * Whether the input should be disabled. */ disableInput?: (allSettingsValues: T) => boolean; } /** * A setting type that allows users to configure an icon from a pick list. */ export interface IconSetting extends SettingBase, IdentifiableSetting { /** * @inheritdoc */ type: "icon"; } /** * An input type control that allows users to upload files. */ export interface ImageSetting extends SettingBase, IdentifiableSetting, RequirableSetting, ValidatableSetting { /** * @inheritdoc */ type: "image"; /** * A list of valid 'accept' attribute values on the input element. */ accept: string[]; } /** * A Setting type that is read only. */ export interface LabelSetting extends SettingBase, IdentifiableSetting { /** * @inheritdoc */ type: "label"; } /** * A Setting type that allows navigation between settings forms. */ export interface LinkSetting extends SettingBase { /** * @inheritdoc */ type: "link"; /** * The ID of the setting. */ id: string; /** * The linked setting. */ link: LinkInfo; } interface CommonListSettings { /** * Whether the list is edited in place, meaning the user does not drill in * to edit the item. */ inPlace?: boolean; /** * Whether the list can be reordered by the user. */ sortable: boolean; } /** * A list of items, which can be added to, removed from, reordered, or edited. */ export interface ListSetting extends SettingBase, IdentifiableSetting, ValidatableListSetting, CommonListSettings { /** * @inheritdoc */ type: "list"; /** * The different types of items which are valid in the list. */ itemTypes: ListItemType[]; /** * Providing a value allows the user to pick items from a filterable list. * This is useful when the user needs to select a subset of items from a * potentially large list. */ availableItems?: ListItemSettings[] | ((allSettingsValues: T) => ListItemSettings[]); } /** * A list of portal items, which can be added to, removed from, reordered, or * edited. */ export interface PortalListSetting extends SettingBase, IdentifiableSetting, ValidatableListSetting, CommonListSettings { /** * @inheritdoc */ type: "portalList"; /** * The different types of items which are valid in the list. */ itemTypes: PortalListItemType[]; /** * Whether to include the content of the portal item. */ includePortalItemContent?: boolean; } /** * An input type control that allows a user to pick a portal item from a dialog. */ export interface PortalItemInputSetting extends SettingBase, IdentifiableSetting, ValidatableSetting, RequirableSetting, PortalItemQueryTypes { /** * @inheritdoc */ type: "portalItem"; } /** * An input type control that has additional functionality to help the user * create Markdown. */ export interface MarkdownSetting extends SettingBase, IdentifiableSetting { /** * @inheritdoc */ type: "markdown"; } /** * An input setting type that accepts a number value. */ export interface NumberInputSetting extends SettingBase, IdentifiableSetting, RequirableSetting, DisableableSetting, ValidatableSetting { /** * @inheritdoc */ type: "number"; /** * The maximum (numeric or date-time) value for this item, which must not be * less than its minimum (min attribute) value. Can also take a function * that will be called with current settings data to produce a number. */ max?: number | ((allSettingsValues: T) => number); /** * The minimum (numeric or date-time) value for this item, which must not be * greater than its maximum (max attribute) value. Can also take a function * that will be called with current settings data to produce a number. */ min?: number | ((allSettingsValues: T) => number); /** * The step attribute specifies the size of each movement (an increment or * jump between values) of the slider control. Slider control is visible * when both max and min is specified. If not specified, the step size will * be calculated using the range between min and max and will be 0.1 for a * range < 10, 1 for 10 <= range < 100, and so on. The number of steps on * the number slider will be between 10 & 99 inclusive. */ step?: number; } /** * An input setting type that accepts a text value and masks the typed * characters. */ export interface PasswordSetting extends SettingBase, IdentifiableSetting, RequirableSetting, DisableableSetting, ValidatableSetting { /** * @inheritdoc */ type: "password"; } /** * A Setting type that allows users to select from a list of predefined values. */ export interface SelectSetting extends SettingBase, IdentifiableSetting, RequirableSetting { /** * @inheritdoc */ type: "select"; /** * Whether the drop down supports selecting multiple items. */ allowMultiple?: boolean; /** * The values to be displayed in the select control. This can either be a * static array of values, or a function that generates the values based on * other settings. */ values: SelectValue[] | ((allSettingsValues: T) => SelectValue[]); } /** * Parameters for filtering a set of options. */ export interface TagsSettingOptionsParams { /** * An optional search term. This allows for either a new query or to filter * the existing results. */ searchTerm?: string; /** * An optional filter. This allows for differing queries not solely based on * the searchTerm. For example each filter could correspond to a different * REST endpoint. */ filter?: string; } /** * A select option for a tags setting. */ export interface TagsSettingSelectValue extends SelectValue { /** * Further information to be displayed to the user. Helpful for displaying * why their search term / filter has returned certain results. */ secondaryInformation?: string[]; } /** * A Setting type that allows a user to configure 0 or more tags. Duplicate tags * will automatically be filtered out. */ export interface TagsSetting extends SettingBase, IdentifiableSetting, ValidatableSetting { /** * @inheritdoc */ type: "tags"; /** * When used in combination with `options` a select control will be * rendered. This allows for differing queries not solely based on the * search term. For example each filter could correspond to a different REST * endpoint. */ filters?: SelectValue[]; /** * If provided the user will be able to choose from an autocomplete list of * options. */ options?: TagsSettingSelectValue[] | ((args: TagsSettingOptionsParams) => Promise); } /** * An input setting type that accepts a text value. */ export interface TextInputSetting extends SettingBase, IdentifiableSetting, RequirableSetting, DisableableSetting, ValidatableSetting { /** * @inheritdoc */ type: "text"; /** * If `true`, a textarea element will be rendered. */ multiline?: boolean; } /** * A Setting type that allows users to control the size of a component. */ export interface SizingSetting extends SettingBase, IdentifiableSetting { /** * @inheritdoc */ type: "sizing"; } /** * A Setting type that allows users to select from a list of predefined values * presented as separate toggle buttons. */ export interface ToggleSetting extends SettingBase, IdentifiableSetting { /** * @inheritdoc */ type: "toggle"; /** * The values to be displayed in the toggle control. This can either be a * static array of values, or a function that generates the values based on * other settings. */ values: ToggleValue[] | ((allSettingsValues: T) => ToggleValue[]); } /** * A Setting type that allows users to setup a button with icons and a label. */ export interface ButtonSetting extends Omit, "displayName">, IdentifiableSetting, ConfirmationDialogSettings { /** * @inheritdoc */ type: "button"; /** * The icon to be included in the button. */ iconId?: string; /** * The label for this setting. */ displayName?: string; /** * Callback for when the button is clicked. */ onClick?: () => void | Promise; /** * Label for the button tooltip. */ tooltipLabel?: string; /** * Toggle to allow user to only have an icon button, without a label. * Defaults to 'false'. */ hideLabel?: boolean; /** * If true, the button is disabled until the app is saved. */ disableUntilAppSaved?: boolean; /** * Whether or not to save the app after the button is clicked. */ saveAfter?: boolean; } /** * Interface for confirmation dialog settings. */ export interface ConfirmationDialogSettings { /** * Whether or not to display a confirm dialog. */ displayConfirmDialog?: boolean; /** * Title of confirm dialog. */ confirmDialogTitle?: string; /** * Description of confirm dialog. */ confirmDialogDescription?: string; /** * Cancel button text on dialog. */ confirmDialogCancelButtonText?: string; /** * Confirm button text on dialog. */ confirmDialogConfirmButtonText?: string; } /** * An item in a SelectSetting list of predefined values. */ export interface SelectValue { /** * The label that is displayed in the select control. */ displayName: string; /** * When provided, the corresponding image is displayed next to the display * name of the value. Can be data-url for an svg or a url to an image. */ imageUrl?: string; /** * The value that is used when this option is selected. */ value: string; } /** * An item in a ToggleSetting list of predefined values. */ export interface ToggleValue { /** * The label that is displayed in the toggle control. */ displayName: string; /** * The icon to be included in the toggle. */ iconId?: string; /** * The value that is used when this option is selected. */ value: string; } /** * Represents a single state in a multi-state toggle. */ export interface ListItemToggleState { /** * The value of the toggle state. */ value: string; /** * The ID of the icon to be shown in the list item. */ iconId: string; /** * The display name for this toggle state. */ displayName: string; } /** * A toggle which allows the user to cycle through multiple states within a list * item. */ export interface ListItemMultiStateToggleSetting extends IdentifiableSetting { /** * The states for the toggle, in order. */ states: ListItemToggleState[]; /** * If the toggle button is visible in the UI. */ isVisible?: (data: T) => boolean; } /** * A toggle which allows the user to configure a boolean property within a list * item. */ export interface ListItemToggleSetting extends IdentifiableSetting { /** * The ID of the icon to be shown in the list item. */ iconId: string; /** * If the toggle button is visible in the UI. */ isVisible?: (data: T) => boolean; /** * The current state of the toggle when toggled off. */ toggledOffDisplayName: string; /** * The current state of the toggle when toggled on. */ toggledOnDisplayName: string; } /** * The types of list items that could be within a `ListSetting`. A * `ListItemType` is associated with an object interface `T` which corresponds * to a subset of the list item's settings schema. For example, `T` could be * {displayName: string, url: string} but the settings schema for the list item * is a full settings for a feature layer. */ export interface ListItemType { /** * The title displayed on the add button, e.g "Print Templates" would be * shown as "Add Print Templates". The presence of this determines if the * list item can be added / deleted. */ addItemTitle?: string; /** * If no `addItemTitle` is provided, this allows the item to be removed from * the list. If `addItemTitle` is provided this property does nothing. */ canDelete?: boolean | ((id: string) => boolean); /** * On the creation of a new list item, this value will be passed to * `getSettings` and `getSettingsSchema` to display the appropriate * settings. If no `creationSubsettingsType` is provided, the created item * will use its `subsettingsType` as the `creationSubsettingsType`. */ creationSubsettingsType?: string; /** * Whether to drill into the item after creation. Defaults to false. */ editAfterCreation?: boolean; /** * The type of list item. E.g "menu-item". This value is on existing items * and will be passed to `getSettings` and `getSettingsSchema` to display * the appropriate settings. */ subsettingsType: string; /** * The toggle buttons which allow configuration from the list item. */ toggles?: (ListItemToggleSetting | ListItemMultiStateToggleSetting)[]; /** * Option to use item creation dialog instead of portal explorer. */ useItemCreationDialog?: boolean; } /** * Controls how Portal item options are presented to the user. */ export interface PortalItemQueryTypes { /** * An additional clause to add to the search query. */ additionalClause?: string; /** * A list of possible item types. */ portalItemTypes?: string[]; /** * A list of type keywords that all must be present in a portal item. */ portalItemTypeKeywords?: string[]; /** * Whether to search publicly or just within the organization. */ searchDomain: SearchDomain; /** * Whether or not to show the thumbnail and grid view. */ showThumbnail?: boolean; } /** * List item type for the Portal item list. */ export interface PortalListItemType extends PortalItemQueryTypes, ListItemType { } /** * An item within a ListSetting. These are the settings that are used to * represent an individual item in a list. */ export interface ListItemSettings { /** * The unique ID of the ListItem. */ id: string; /** * The ID of the ListItemType. */ itemTypeId: string; /** * The data of the list item. This contains values for list item toggles for * example. */ data?: TData; /** * Determines if a list item can be drilled into. */ canDrillIn?: boolean; /** * The title of the list item. */ title: string; } /** * The information needed to link from one component to another, or to an * external URL. Either key or url is required, to specify if the redirect * should be between components/services, or to an external URL. */ export interface LinkInfo { /** * The human-readable title for the link. */ title: string; /** * The key identifying the configurable item to link to. */ key?: ConfigurableItemKey; /** * The url setting, to redirect to any external URL. */ url?: { href: string; }; } /** * The settings' IDs of the component or service. */ export interface SettingsIds { config: string[]; layout: string[]; } export {};