/**
 * Object containing helper methods for generating optimal symbols for data-driven size visualizations.
 * The [getSchemes()](https://developers.arcgis.com/javascript/latest/references/core/smartMapping/symbology/size/#getSchemes) method is used to generate symbol properties best suited to
 * the given geometry type and basemap.
 *
 * @since 4.2
 */
import type Basemap from "../../Basemap.js";
import type SceneView from "../../views/SceneView.js";
import type { SizeScheme, SizeSchemes, BasemapTheme, Theme } from "./types.js";

/**
 * Returns metadata for the available themes. If a basemap is provided, returns themes that work best
 * with the given basemap.
 *
 * @param basemap - The [Esri basemap string](https://developers.arcgis.com/javascript/latest/references/core/Map/#basemap)
 *   or object that will be used with the returned theme(s).
 * @returns Returns an object containing information about the available themes for the given basemap.
 */
export function getThemes(basemap?: Basemap | string | null | undefined): Theme[];

/**
 * Returns a primary scheme and secondary schemes defining symbol properties for size-based
 * data-driven visualizations in
 * a [FeatureLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/FeatureLayer/). The `basemap` parameter determines the color of the
 * graphics used to visualize each feature. The `geometryType` determines which type of symbol to return.
 *
 * @param params - The function parameters.
 * @returns Returns an object containing the optimal size scheme to use for the given
 *   basemap and secondary schemes that may also be used.
 * @example
 * // gets the primary scheme for the features of the given geometry type and basemap
 * let schemes = sizeSchemes.getSchemes({
 *   basemap: map.basemap,
 *   geometryType: featureLayer.geometryType
 * });
 *
 * // the best default scheme for the layer and basemap
 * let primaryScheme = schemes.primaryScheme;
 */
export function getSchemes(params: GetSchemesParameters): SizeSchemes | null | undefined;

/**
 * Clones a size scheme object.
 *
 * @param scheme - The SizeScheme object to clone.
 * @returns Returns a clone of the given size scheme object.
 * @example
 * // clones the primary scheme returned from the getSchemes() method
 * let sizeScheme = primaryScheme.clone();
 */
export function cloneScheme(scheme: SizeScheme | null | undefined): SizeScheme | null | undefined;

export interface GetSchemesParameters {
  /**
   * The Esri basemap to pair with the visualization. This
   *   value indicates the best symbol colors for visualizing features against the given basemap. If you have a
   *   non-Esri basemap (e.g. a VectorTileLayer basemap with a custom style) or no basemap at all, then use the `basemapTheme` parameter
   *   instead of this parameter.
   */
  basemap?: Basemap | string | null;
  /** The geometry type of the features to visualize. */
  geometryType: "point" | "multipoint" | "polyline" | "polygon" | null;
  /**
   * If you have a
   *   non-Esri basemap (e.g. a VectorTileLayer basemap with a custom style) or no basemap at all, use this parameter to indicate
   *   whether the background of the visualization is `light` or `dark`.
   */
  basemapTheme?: BasemapTheme | null;
  /**
   * Indicates if the size units of the scheme will be in meters.
   * This should be `true` when the scheme is intended for 3D volumetric symbology.
   * A `view` must be provided if this property is set to `true`.
   */
  worldScale?: boolean | null;
  /**
   * The SceneView instance in which the scheme
   * will be used. This property is only applicable when the scheme will be used in conjunction with 3D symbols.
   */
  view?: SceneView | null;
}