@arcgis/coding-components/dist/components/arcgis-arcade-editor/customElement.d.ts

ArcGIS Coding Components

/// <reference path="../../index.d.ts" />
import type { editor as Editor } from "monaco-editor";
import type { Diagnostic } from "@arcgis/arcade-languageservice";
import type { ApiSnippet } from "@arcgis/languages-api-utils";
import type { PublicLitElement as LitElement } from "@arcgis/lumina";
import type { EditorCodeSuggestion, EditorCodeSuggestionGroup, EditorProfileDefinition, IEditorCodeSuggestion, IEditorCodeSuggestionGroup, IEditorProfileDefinition, IEditorTestContext, IPredefinedProfile, PredefinedProfile, EditorTestContext } from "../types.js";
import type { ArcadeResult, EditorExternalExecutor } from "../../utils/arcade-executor.js";
import type { ICustomPanel } from "../../utils/custom-panel.js";
import type { ArcadeAssistantConfig } from "../../utils/arcade-assistant/types.js";
import type { T9nMeta } from "@arcgis/lumina/controllers";

/**
 * [**Arcade**](https://developers.arcgis.com/arcade/) is a portable, and lightweight expression language used to create custom content throughout the [ArcGIS system](https://www.esri.com/en-us/arcgis/products/index).
 * Like other expression languages, it can perform mathematical calculations, format text, and evaluate logical statements.
 * It also supports multi-statement expressions, variables, and flow control statements. Arcade is unique when compared to other expression and scripting languages due to its inclusion of [feature](https://developers.arcgis.com/arcade/guide/types/#feature) and [geometry](https://developers.arcgis.com/arcade/guide/types/#geometry) data types.
 *
 * Map Viewer (MV) was the first ArcGIS Online product to incorporate the new Arcade editor after [the editor's introduction in the November 2022 ArcGIS Online release](https://www.esri.com/arcgis-blog/products/arcgis-online/mapping/introducing-the-new-arcade-editor-in-arcgis-online/).
 * This was possible thanks to the Arcade editor component, which enabled MV to implement its own Arcade expression builder.
 * You can now also find the editor in ArcGIS Dashboards, ArcGIS Field Maps, and ArcGIS Velocity.
 *
 * You can easily get your own dedicated Arcade expression builder with the **Arcade editor** component, which includes:
 *
 * - An easy to use [layout](https://www.esri.com/arcgis-blog/products/arcgis-online/mapping/discover-the-arcade-editors-powerful-new-features/#the-new-layout)
 * - An optional minimal layout if you, for example, decide to manually exclude things such as test data, padding, line numbers, and the sidebar
 * - A way to execute Arcade expressions in a configurable code editor
 * - [Suggestions and code completion](https://www.esri.com/arcgis-blog/products/arcgis-online/mapping/discover-the-arcade-editors-powerful-new-features/#suggestions-and-code-completion)
 * - [WCAG 2.0 compliant code colorization / syntax highlighting](https://www.esri.com/arcgis-blog/products/arcgis-online/mapping/accessibility-and-arcade-working-in-color/)
 * - Built-in [keyboard shortcuts](https://www.esri.com/arcgis-blog/products/arcgis-online/mapping/discover-the-arcade-editors-powerful-new-features/#keyboard-shortcuts)
 * - In-editor help for finding information about profile variables relevant to your profile, documentation for constants and functions, a link to the official Arcade documentation, and, in some case, suggestions
 * - Support for many [languages and directionality](https://developers.arcgis.com/javascript/latest/localization/)
 * - A debugger with support for breakpoints, stepping, and an interactive console
 * - An [AI Assistant](https://doc.arcgis.com/en/arcgis-online/create-maps/understand-arcade-assistant.htm) that uses natural language
 * processing to generate Arcade expressions from scratch or find and fix errors in your code
 *
 * The Arcade editor and some of the underlying core Arcade language functions depend on esriConfig properties. To ensure the best experience for your users,
 * make sure to set the following:
 * - [esriConfig.applicationName](https://developers.arcgis.com/javascript/latest/references/core/config/#Config-applicationName)
 *   - Used by the [GetEnvironment()](https://developers.arcgis.com/arcade/function-reference/debugging_functions/#getenvironment) Arcade function
 *   - Associates feedback to the Arcade assistant with a specific application
 * - [esriConfig.portalUrl](https://developers.arcgis.com/javascript/latest/references/core/config/#Config-portalUrl)
 *   - Required for the Arcade assistant to function, as the assistant relies on ArcGIS Online services
 */
export abstract class ArcgisArcadeEditor extends LitElement {
  /**
   * enables and configures the arcade assistant
   *
   * @deprecated since 5.1. Use { \@link components/arcade-editor#disableAssistant } instead.
   * @internal
   */
  accessor arcadeAssistant: ArcadeAssistantConfig | undefined;
  /**
   * Custom panels to be displayed in the side panel.
   * Will be placed below the default panels but above the help panel.
   *
   * @internal
   */
  accessor customPanels: ICustomPanel[] | undefined;
  /**
   * When set to `true`, hides the Arcade assistant (beta) panel and disables all related features.
   * The Arcade assistant (beta) panel includes a question/answer UX that allows
   * users to ask the assistant to generate Arcade expressions from natural language prompts, or to find and fix errors in their code.
   *
   * The Arcade assistant (beta) will only be available if the following conditions are met:
   * - The `disableAssistant` property is `false`
   * - The [esriConfig.portalUrl](https://developers.arcgis.com/javascript/latest/references/core/config/#Config-portalUrl) is set to an ArcGIS Online portal (either the default or a custom one)
   * - The user is signed in to the portal. The application exposing the editor must handle user authentication.
   * - The signed in user has permissions to use AI features in ArcGIS Online, including the following conditions:
   *   - The user's organization allows use of AI assistants,
   *   - The user's role has the "Use AI assistants" privilege enabled, and
   *   - Beta features are enabled for the user's organization
   *
   * The assistant also provides the ability for users to submit feedback on generated responses, which may be used to improve the assistant's performance over time.
   * When feedback is logged, it is associated with the application exposing the Arcade editor. It is best practice to set
   * [esriConfig.applicationName](https://developers.arcgis.com/javascript/latest/references/core/config/#Config-applicationName) so the feedback can be associated with a specific application.
   *
   * More information about the Arcade assistant, including best practices, the context provided to the underlying model, limitations,
   * and transparency cards can be found in the links below.
   *
   * @default false
   * @since 5.1
   * @see [Arcade assistant user documentation](https://doc.arcgis.com/en/arcgis-online/create-maps/understand-arcade-assistant.htm)
   * @see [Arcade assistant best practices and limitations](https://doc.arcgis.com/en/arcgis-online/create-maps/use-arcade-assistant.htm)
   */
  accessor disableAssistant: boolean;
  /**
   * Options to update on the editor.
   * For example:
   * ```json
   * {
   *   "fontSize": 18
   * }
   * ```
   *
   * To get the full list of available options, see the Monaco Editor options [documentation](https://microsoft.github.io/monaco-editor/docs.html#interfaces/editor_editor_api.editor.IEditorOptions.html) for more details.
   */
  accessor editorOptions: (Editor.IEditorOptions & Editor.IGlobalEditorOptions) | undefined;
  /**
   * If `true`, the editor will enable a debug drawer at the bottom of the editor. This drawer
   * includes debugging features such as the ability to set breakpoints, step through code,
   * and view variable values during execution.
   *
   * @default false
   * @since 5.1
   */
  accessor enableDebugger: boolean;
  /**
   * External executor function, if provided, execution will be passed off to this function instead of the built-in executor.
   *
   * For information on how to implement see { \@link stories/details/external-executor.mdx }
   *
   * @internal
   * @example
   * ```tsx
   * const myExternalExecutor = cSharpBindings.getExecutor();
   * const externalExecutor: EditorExternalExecutor = async ({ mode, script, console, breakpoints, onDebugPause, signal }) => {
   * if (mode === "run") {
   *   return await myExternalExecutor.run(script, { signal, console });
   * } else if (mode === "debug") {
   *   return await myExternalExecutor.debug(script, { signal, console, breakpoints, onDebugPause });
   * }
   *
   * return <arcgis-arcade-editor externalExecutor={{ execute: externalExecutor }} />
   * ```
   */
  accessor externalExecutor: EditorExternalExecutor | undefined;
  /**
   * If true, it will hide the documentation action in the side panel
   *
   * @default false
   */
  accessor hideDocumentationActions: boolean;
  /**
   * If true, it will hide the side actions bar. The editor will be in a minimalistic UX.
   *
   * @default false
   */
  accessor hideSideBar: boolean;
  /**
   * Replace localized message strings with your own strings.
   *
   * **Note**: Individual message keys may change between releases.
   */
  accessor messageOverrides: {
      help?: string | undefined;
      profilevariables?: string | undefined;
      constantsandfunctions?: string | undefined;
      suggestions?: string | undefined;
      run?: string | undefined;
      runanddebug?: string | undefined;
      continue?: string | undefined;
      reset?: string | undefined;
      stop?: string | undefined;
      lastresults?: string | undefined;
      close?: string | undefined;
      output?: string | undefined;
      console?: string | undefined;
      log?: string | undefined;
      debugconsole?: string | undefined;
      arcadeassistant?: string | undefined;
      askarcadeassistant?: string | undefined;
      askarcadeassistantprompt?: string | undefined;
      profileempty?: string | undefined;
  };
  /** @internal */
  protected messages: Partial<{
      help: string;
      profilevariables: string;
      constantsandfunctions: string;
      suggestions: string;
      run: string;
      runanddebug: string;
      continue: string;
      reset: string;
      stop: string;
      lastresults: string;
      close: string;
      output: string;
      console: string;
      log: string;
      debugconsole: string;
      arcadeassistant: string;
      askarcadeassistant: string;
      askarcadeassistantprompt: string;
      profileempty: string;
  }> & T9nMeta<{
      help: string;
      profilevariables: string;
      constantsandfunctions: string;
      suggestions: string;
      run: string;
      runanddebug: string;
      continue: string;
      reset: string;
      stop: string;
      lastresults: string;
      close: string;
      output: string;
      console: string;
      log: string;
      debugconsole: string;
      arcadeassistant: string;
      askarcadeassistant: string;
      askarcadeassistantprompt: string;
      profileempty: string;
  }>;
  /**
   * The name of the opened side panel. 'none' means 'no panel opened'.
   *
   * @default "none"
   */
  accessor openedSidePanel: string;
  /**
   * The profile contains metadata used by the editor for editing context and help.
   * Example:
   * ```
   *  {
   *    bundles: ["core", "dataAccess", "geometry", "portal-access"],
   *    variables: [
   *      {
   *        name: "$feature",
   *        description: "The feature passed to the script during execution.",
   *        definition: aFeatureLayerInstance
   *      }
   *    ]
   *  }
   * ```
   */
  accessor profile: EditorProfileDefinition | IEditorProfileDefinition | IPredefinedProfile | PredefinedProfile | undefined;
  /**
   * The arcade script. Use this property to define or update the script.
   *
   * @default ""
   */
  accessor script: string;
  /**
   * If true, the side action bar will be expanded
   *
   * @default false
   */
  accessor sideActionBarExpanded: boolean;
  /** Collection of snippets */
  accessor snippets: ApiSnippet[] | undefined;
  /** Collection of suggestions */
  accessor suggestions: EditorCodeSuggestion[] | EditorCodeSuggestionGroup[] | IEditorCodeSuggestion[] | IEditorCodeSuggestionGroup[] | undefined;
  /** Test data used to execute the script in the editor. If undefined the execute script UX will be hidden. */
  accessor testData: EditorTestContext | IEditorTestContext | undefined;
  /**
   * Returns the Arcade result for the script for the provided test data.
   *
   * @internal
   */
  getTestResult(): Promise<ArcadeResult>;
  /**
   * Opens the Arcade assistant side panel and optionally pre-fills the prompt input.
   *
   * @param options
   * @internal
   */
  openArcadeAssistant(options?: { prompt?: string; }): Promise<boolean>;
  /** Set the focus on the element. */
  setFocus(): Promise<void>;
  /** Emitted when the diagnostics collection has changed. */
  readonly arcgisDiagnosticsChange: import("@arcgis/lumina").TargetedEvent<this, Diagnostic[]>;
  /** Emitted when the script string has changed. */
  readonly arcgisScriptChange: import("@arcgis/lumina").TargetedEvent<this, string>;
  readonly "@eventTypes": {
    arcgisDiagnosticsChange: ArcgisArcadeEditor["arcgisDiagnosticsChange"]["detail"];
    arcgisScriptChange: ArcgisArcadeEditor["arcgisScriptChange"]["detail"];
  };
}