Formular-Widget: Signatur

// Get a widget instance
// Please note that widgets instances should be obtained when needed and not cached.
const widget = await $.xutil.xSignatureApi.instance("[data-name=sig1]");

// Get a data URI with the image of the signature
// 'data:image/png;base64,iVBORw0KGgoA...'
await widget.getDataUri()

// Clear the drawn signature
await widget.clear()

/**
 * Base entry point for interacting with the signature widget programmatically. The entry
 * point is exposed via `$.xutil.xSignatureApi`. Due to the asynchronous nature of the
 * signature widget, most methods return `Promise`s.
 *
 * For example:
 *
 * ```js
 * // Get a widget instance
 * // Please note that widgets instances should be obtained when needed and not cached.
 * const widget = await $.xutil.xSignatureApi.instance("[data-name=sig1]");
 *
 * // Get a data URI with the image of the signature
 * // 'data:image/png;base64,iVBORw0KGgoA...'
 * await widget.getDataUri()
 *
 * // Clear the drawn signature
 * await widget.clear()
 * ```
 */
export interface ISignatureApi {
  /**
   * Creates a new API wrapper for the given signature widget element. The API wrapper can be
   * used to interact with the signature widget programmatically.
   * @param signatureElement Either the element widget the class `CXSignature`, or any
   * child thereof. May be either a native HTMLElement or list of HTMLElements, a JQuery
   * wrapper, or a CSS selector string.
   * @returns A list with all signature widgets.
   */
  instance(signatureElement: TElementSpecifier<HTMLElement>): Promise<ISignatureWidget>;

  /**
   * Finds all signature widget instances within the base element. If the base element is
   * a signature widget instance or a child there of, that signature widget is returned.
   * @param base Base element where to search to signature widgets. May be either a native
   * HTMLElement or list of HTMLElements, a JQuery wrapper, or a CSS selector string.
   * @returns A list with all signature widgets.
   */
  instances(base?: TElementSpecifier<HTMLElement>): Promise<ISignatureWidget[]>;

  /**
   * Returns a promise that resolves when the given signature widget was rendered
   * and the user can interact with it.
   *
   * A signature widget is initialized when it is visible, to prevent UI bugs.
   *
   * Note: If the user never navigates to the page containing the signature widget, the
   * returned promise may never be settled!
   *
   * Consider using {@link instance} if you just want to e.g. retrieve data from the signature.
   * @param signatureElement Either the element widget the class `CXSignature`, or any
   * child thereof. May be either a native HTMLElement or list of HTMLElements, a JQuery
   * wrapper, or a CSS selector string.
   */
  whenRendered(signatureElement: TElementSpecifier<HTMLElement>): Promise<ISignatureWidget>;
}

/**
 * Represents an instance of a particular map widget. Offers methods to
 * interact with the widget programmatically.
 *
 * See {@link ISignatureApi} for how to obtain widget instances.
 */
export interface ISignatureWidget {
  /**
   * Clears the signature, if any signature is present.
   */
  clear: () => Promise<void>;

  /**
   * Gets the container element of this signature widget.
   * @returns The container element of the signature widget, with the class `CXSignature`.
   */
  container: () => HTMLElement;

  /**
   * Gets the contents of the signature as an image, encoded as a data URI.
   * @param type A string indicating the image format. The default type is `image/png`; this image format
   * will be also used if the specified type is not supported.
   * @returns An image with the contents of the signature, as a data URI; or `undefined` when
   * the signature is empty (i.e. no stroke was drawn).
   */
  getDataUri: (type?: string) => Promise<string | undefined>;

  /**
   * Checks if the widget was already rendered. A signature widget is rendered only
   * once it is visible, to prevent UI bugs.
   * @return true if the widget was rendered already, false otherwise.
   */
  rendered(): boolean;

  /**
   * (Re-)renders the widget, if possible. A signature widget can be rendered only
   * when it is visible, to prevent UI bugs.
   */
  renderIfPossible(): Promise<void>;
}

/**
 * Union of types that can be interpreted as referencing to one or multiple
 * (DOM) elements.
 * - `undefined` and `null` are represent a missing element.
 * - `TElement` is the element itself.
 * - `TElement[]` is an array of elements.
 * - `NodeListOf<TElement>` is a list of elements, returned by
 * `querySelectorAll`.
 * - `HTMLCollectionOf<TElement>` is a collection of elements, returned by
 * `getElementsByClassName`.
 * - `string` is a CSS selector for the element(s).
 * - `JQuery` is a JQuery wrapper with the element(s).
 * @typeParam TElement - Type of the DOM element.
 * @returns A union type with various different types corresponding to an
 * element.
 */
type TElementSpecifier<TElement extends Element> =
 | undefined
 | null
 | TElement
 | TElement[]
 | (NodeList & NodeListOf<TElement>)
 | (HTMLCollection & HTMLCollectionOf<TElement>)
 | string
 | JQuery<TElement>;