@arcgis/core/widgets/support/widget.d.ts

ArcGIS Maps SDK for JavaScript: A complete 2D and 3D mapping and data visualization API

/**
 * This module contains widget helpers.
 *
 * @since 4.2
 * @see [Accessor](https://developers.arcgis.com/javascript/latest/references/core/core/Accessor/)
 * @see [decorators](https://developers.arcgis.com/javascript/latest/references/core/core/accessorSupport/decorators/)
 * @see [Guide - Implementing Accessor](https://developers.arcgis.com/javascript/latest/implementing-accessor/)
 * @see [Guide - Watching for changes](https://developers.arcgis.com/javascript/latest/watch-for-changes/#watch-for-changes-in-the-api)
 * @see [Guide - Watching for component changes](https://developers.arcgis.com/javascript/latest/watch-for-changes/)
 * @see [Guide - Get started: TypeScript](https://developers.arcgis.com/javascript/latest/get-started/#typescript)
 */
import type Widget from "../Widget.js";

/**
 * This convenience decorator is used to help simplify accessibility within the widget keyboard events.
 * For example, it can be used to execute a method when the `space` or `enter` keys are pressed.
 *
 * @returns The property descriptor.
 * @since 4.2
 * @example
 * // .tsx syntax providing accessibility on a widget method
 * \@accessibleHandler()
 * reset: () => void;
 */
export function accessibleHandler(): PropertyDecorator;

/**
 * This convenience decorator is used to help simplify localization of the widget.
 * It is useful to decorate a property that will be automatically populated with the
 * localized message bundled specified by the identifier `bundleId`.
 * The property can then be used in the `render()` function to display the localized content.
 *
 * When a widget is instantiated, all of the message bundles are loaded and assigned to their
 * corresponding properties. The widget's [Widget.postInitialize()](https://developers.arcgis.com/javascript/latest/references/core/widgets/Widget/#postInitialize)
 * method is called, followed by the first call to [Widget.render()](https://developers.arcgis.com/javascript/latest/references/core/widgets/Widget/#render).
 *
 * When the locale changes, all of the message bundles for all of the active widgets are reloaded and reassigned.
 * The widgets then render simultaneously.
 *
 * If functions are working with translated strings outside of a widget, use [fetchMessageBundle()](https://developers.arcgis.com/javascript/latest/references/core/intl/#fetchMessageBundle)
 * instead.
 *
 * > [!WARNING]
 * >
 * > Note that the first call to `render()` only occurs after all the properties decorated with `@messageBundle`
 * > have been populated with their corresponding bundle.
 *
 * @param bundleId - The bundle identifier passed to [fetchMessageBundle()](https://developers.arcgis.com/javascript/latest/references/core/intl/#fetchMessageBundle).
 * @returns The property decorator.
 * @since 4.18
 * @see [fetchMessageBundle()](https://developers.arcgis.com/javascript/latest/references/core/intl/#fetchMessageBundle)
 * @see [registerMessageBundleLoader()](https://developers.arcgis.com/javascript/latest/references/core/intl/#registerMessageBundleLoader)
 * @example
 * // .tsx syntax to define a message bundle property
 * \@property()
 * \@messageBundle("my-application/MyBundle")
 * messages: { [key: string]: any };
 *
 * render() {
 *   return (
 *     <div>{this.messages.myMessage}</div>
 *   );
 * }
 */
export function messageBundle(bundleId: string): PropertyDecorator;

/**
 * This convenience decorator helps dispatch view model events on the widget instance.
 *
 * @param eventNames - The event names to re-dispatch.
 * @returns The property decorator.
 * @since 4.2
 * @example
 * // .tsx syntax dispatching view model events
 * \@property()
 * \@vmEvent("search, search-clear, suggest")
 * viewModel: SearchViewModel;
 */
export function vmEvent(eventNames: string | string[]): PropertyDecorator;

/**
 * Utility method used to determine if the directionality
 * of the text of the document is right-to-left.
 *
 * @returns `true` if the directionality
 * of the text of the document is right-to-left.
 * @since 4.9
 */
export function isRTL(): boolean;

/**
 * Utility method used for creating CSS animation/transition functions.
 *
 * @param type - The animation/transition type.
 * @param className - The animation/transition class name.
 * @returns The animation/transition function.
 * @since 4.7
 * @example
 * // .tsx syntax showing how to set up node enter/exit animations
 *
 * render() {
 *   const content = this.visible ? (
 *     <div enterAnimation={cssTransition("enter", CSS.fadeIn)}
 *          exitAnimation={cssTransition("exit", CSS.fadeOut)}>
 *       I fade in and out.
 *     </div>
 *   ) : null;
 *
 *   return (
 *     <div class={CSS.base}>{content}</div>
 *   );
 * }
 */
export function cssTransition(type: "enter" | "exit", className: string): any;

/**
 * Utility method used to determine if a pressed key should activate button behavior. If the returned [KeyboardEvent.key](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key) is either `Enter` or a space (`" "`), it returns `true`.
 *
 * @param key - The [KeyboardEvent.key](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key)
 * @returns Indicates whether the pressed [keyboard key](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key) is either `Enter` or a space (`" "`).
 * @since 4.19
 * @see [developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key)
 */
export function isActivationKey(key: KeyboardEvent["key"]): boolean;

/**
 * This convenience method is used to assign an [HTMLElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement) DOM node reference to a variable.
 * It does this by taking a [HTMLElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement) passed from either the `afterUpdate`
 * or `afterCreate` callbacks. In order to use this, the element must have a set
 * `data-node-ref` attribute. In addition, it
 * must also be bound to the widget instance, e.g. `bind={this}`.
 *
 * @param node - The referenced DOM node.
 * @since 4.6
 * @example
 * // The storeNode function is called after the node is
 * // added to the DOM. Bind the node to the widget and
 * // pass in the node's root element name.
 *
 * render() {
 *   return (
 *     <div afterCreate={storeNode} bind={this} data-node-ref="rootNode" />
 *   );
 * }
 */
export function storeNode<T extends Widget>(node: Element): void;

/**
 * This convenience method is used to render the JSX in the [Widget.render()](https://developers.arcgis.com/javascript/latest/references/core/widgets/Widget/#render) method.
 * It is required to import `tsx` even though it is not explicitly called.
 *
 * @param tagNameOrComponent - The element to create.
 * @param properties - The element's properties.
 * @param children - The element's children.
 * @returns The virtual node.
 * @since 4.4
 * @example
 * // .tsx syntax importing jsxfactory
 * import { tsx } from "@arcgis/core/widgets/support/widget.js";
 */
export function tsx(tagNameOrComponent: string | Function, properties: any | null | undefined, ...children: any[]): any;

export namespace tsx {
  namespace JSX {
    interface IntrinsicElements {
      [elementName: string]: any;
    }

    interface Element {
    }
  }
}