Form widget: Map integration

// Get the currently selected geometry, as a set of points
$.xutil.xMapApi.instance("[data-name=map1]").selectedGeometry()

// Select a different type of geometry
$.xutil.xMapApi.instance("[data-name=map1]").selectGeometry({
  type: "area",
  points: [
    {lat: 51.0916,lng: 13.7622},
    {lat: 51.0148, lng: 13.7375},
    {lat: 51.0593, lng: 13.8621}
  ],
})

// Remove the attribution link at the bottom right corner of the map completely for a specific map
$.xutil.xMapApi.whenRendered("[data-org-name=map2]").then(api => api.leafletMap().attributionControl.remove())

// Remove the attribution link at the bottom right corner of the map completely for all maps
$.xutil.xMapApi.addRenderedListener(api => api.leafletMap().attributionControl.remove())

/**
 * API entry point for the XMap widget. Provides methods to access particular
 * map widget instances.
 *
 * For example:
 *
 * If you want to get or set the value of a map widget:
 *
 * ```js
 * // Get the value
 * $.xutil.xMapApi.instance("[data-name=map1]").selectedGeometry()
 *
 * // Set the value
 * $.xutil.xMapApi.instance("[data-name=map1]").selectGeometry({
 * type: "area",
 * points: [{lat: 51.0916,lng: 13.7622}, {lat: 51.0148, lng: 13.7375}, {lat: 51.0593, lng: 13.8621}],
 * })
 * ```
 *
 * If you want to remove the attribution links at the bottom right corner:
 *
 * ```js
 * // For a specific map
 * $.xutil.xMapApi.whenRendered("[data-org-name=map2]")
 * .then(api => api.leafletMap().attributionControl.remove())
 *
 * // For all maps
 * $.xutil.xMapApi.addRenderedListener(api => api.leafletMap().attributionControl.remove())
 * ```
 */
interface IXMapApi {
  /**
   * Adds a listener that is called when a map widget was rendered. Once
   * the widget was rendered, the Leaflet instance can be accessed. This
   * method can be used for logic that should be applied to every map widget.
   *
   * A map widget is rendered only once it has become visible, to avoid UI bugs.
   *
   * If the map widget is already visible, the listener is called
   * immediately (but asynchronously).
   *
   * Each listener is called at most once, but may never be called when the widget
   * is not on the first page and the user navigates to the page with the widget.
   * @param listener Listener to call when the widget is rendered.
   */
  addRenderedListener: (listener: (widget: IXMapWidget) => void) => void;

  /**
   * Removes a listener that was added via {@link addRenderedListener}. The listener
   * will not be invoked anymore for any further widgets when they are rendered.
   * @param listener Listener to remove.
   */
  removeRenderedListener: (listener: (widget: IXMapWidget) => void) => void;

  /**
   * Gets the API for the given map widget from either the container element of a child
   * of the map.
   * @param mapElement A map widget element with the class `XMapContainer`; or
   * any child thereof. Can be a native HTMLElement, a list of HTMLElements, a
   * CSS selector, or a JQuery wrapper.
   * @throws When the given element is not an HTMLElement or not a map element.
   */
  instance: (mapElement: TElementSpecifier<HTMLElement>) => IXMapWidget;

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

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

/**
 * Wraps a particular map widget instance and provides methods for that map widget.
 *
 * Most methods work regardless of whether the map widget was already rendered. The
 * {@link leafletMap} will return undefined when the map widget was not rendered yet.
 */
interface IXMapWidget {
  /**
   * Gets the container element of this map widget.
   * @returns The container element of the map widget, with the class `XMapDiv`.
   */
  container: () => HTMLElement;

  /**
   * Clears the selected geometry, if any geometry was selected.
   * @param silent When `true`, do not fire any change or blur events
   * on the text area element. Defaults to `false`.
   */
  clear: (silent?: boolean) => void;

  /**
   * Whether the widget was already rendered. The widget is rendered only once it has become
   * visible. When the widget was not yet rendered, {@link getLeaflet} returns `undefined`.
   */
  rendered: () => boolean;

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

  /**
   * Gets the currently selected geometry.
   * @returns geometry The geometry currently shown on the map.
   */
  selectedGeometry: () => IXMapGeometry;

  /**
   * Sets the selected geometry to the given value.
   * @param geometry Geometry to show on the map.
   * @param silent When `true`, do not fire any change or blur events
   * on the text area element. Defaults to `false`.
   */
  selectGeometry: (geometry: IXMapGeometry, silent?: boolean) => void;

  /**
   * Queries the browser for the user's current location and adds a marker to
   * the map with the user's location.
   * @returns The position of the user.
   * @throws When the user's location could not be determined. May happen e.g.
   * when the browser does not support the geolocation feature or when the user
   * denied access to their location.
   */
  showGeoLocation: () => Promise<GeolocationPosition>;

  /**
   * Hides the location of the user, if previously shown by {@link showGeoLocation}.
   * When no geo location is currently visible, does nothing.
   */
  hideGeoLocation: () => void;

  /**
   * Gets the instance of the backing Leaflet widget. Can be used for advanced scripting.
   * Note that the leaflet is created only once the map has become visible. This method
   * returns `undefined` when no leaflet exists yet.
   * @returns The instance of the backing Leaflet widget. `undefined` if the map was
   * not rendered yet.
   */
  leafletMap: () => import("leaflet").Map | undefined;

  /**
   * Gets the instance of the backing Leaflet widget. Can be used for advanced scripting.
   * This returns a promise that resolves once the Leaflet widget was created. It is
   * created once the map element becomes visible. If the user never navigates to the
   * page with the widget, it may never become visible and consequently, the returned
   * promise may never be settled.
   * @returns The instance of the backing Leaflet widget.
   */
  waitForLeafletMap: () => Promise<import("leaflet").Map>;
}

/**
 * Describes the value (geometry) that can be selected by the map widget. Consists
 * of the type of the selected geometry (point, line, or area), and a list of points
 * for the geometry.
 */
interface IXMapGeometry {
  /**
   * The type of the geometry, either a point, line, or area.
   */
  readonly type: TGeometryType;

  /**
   * The points of the selected geometry. When the type is `line`,
   * the points are connected in order. When the type is `area`, the
   * points are the corner points of a polygon.
   */
  readonly points: LatLngLiteral[];
}

/**
 * The type of the geometry that can be selected.
 * - point Selects a set of disconnected points
 * - line Select a single line going through all points
 * - area Selects a polygon with the points as its corner points
 */
type TGeometryType = "point" | "line" | "area";

/**
 * A coordinate for a position on the surface of a spheroid object,
 * consisting of a latitude and longitude.
 */
interface LatLngLiteral {
  /** The latitude of the coordinate */
  lat: number;
  /** The longitude of the coordinate */
  lng: number;
}

/**
 * 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>;