/// <reference path="../../index.d.ts" />
import type { PublicLitElement as LitElement } from "@arcgis/lumina";
import type { Layout, TickMode, TickValues } from "./types.js";

/**
 * The ticks component displays visual markers along a line to indicate scale, intervals, or specific values. It is often used in conjunction with the
 * [Slider component](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/). Ticks help users understand the
 * slider’s range and make more precise selections.
 *
 * Tick placement is controlled by the [mode](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-ticks/#mode), which defines how the [values](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-ticks/#values) are parsed and translated into positions along the
 * line. Tick positions are derived from the component’s [min](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-ticks/#min) and [max](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-ticks/#max) range, with optional non-linear scaling via
 * [interpolationExponent](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-ticks/#interpolationExponent). Ticks can be displayed in vertical or horizontal [layout](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-ticks/#layout), with optional [showLabels](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-ticks/#showLabels) and a [showBaseline](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-ticks/#showBaseline).
 * The component can also be made [interactive](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-ticks/#interactive) to respond to user clicks on individual ticks. The [labelFormatter](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-ticks/#labelFormatter) property allows customization of tick label formatting.
 *
 * @cssproperty [--arcgis-ticks-tick-length] - Specifies the length of the ticks.
 * @cssproperty [--arcgis-ticks-tick-color] - Specifies the color of the ticks.
 * @cssproperty [--arcgis-ticks-gap] - Specifies the gap between the ticks and labels.
 * @since 5.0
 * @example
 * The following example creates a vertical slider with ticks.
 * The ticks are positioned at the end of the slider and displayed every 10 units from 0 to 100.
 * ```html
 * <arcgis-slider id="sliderComponent" min="0" max="100" show-range-labels values="50" layout="vertical">
 *    <arcgis-ticks slot="content-end" style="flex:1;"
 *      min="0" max="100"
 *      mode="value"
 *      show-labels
 *      label-placement="end"
 *      values="0, 10, 20, 30, 40, 50, 60, 70, 80, 90, 100"
 *      layout="vertical">
 *    </arcgis-ticks>
 * </arcgis-slider>
 * ```
 */
export abstract class ArcgisTicks extends LitElement {
  /**
   * When `true`, ticks are clickable and the component emits [@arcgisTickClick](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-ticks/#event-arcgisTickClick) when the user selects a tick.
   *
   * @default false
   * @see [@arcgisTickClick](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-ticks/#event-arcgisTickClick)
   */
  accessor interactive: boolean;
  /**
   * The exponent used to interpolate the position of ticks along the component.
   * A value of `0` indicates linear interpolation. Positive values indicate exponential interpolation, and negative values indicate logarithmic interpolation.
   *
   * Set this property when the range of values is large and users need precision in the lower range of values (for an exponential interpolation), or in the higher range (for a logarithmic interpolation).
   *
   * ```tsx
   * <arcgis-ticks interpolation-exponent={14} min={1} max={5518000} mode="value" values={[1, 11500, 5518000]} />
   * ```
   *
   * @default 0
   */
  accessor interpolationExponent: number;
  /**
   * Allows customizing how tick labels are formatted based on their numeric value.
   *
   * @example
   * The following example formats tick labels as percentages.
   * ```js
   * const ticks = document.querySelector("arcgis-ticks");
   * ticks.labelFormatter = (value, defaultFormatter) => {
   *   return value + "%";
   * };
   * ```
   */
  accessor labelFormatter: (value: number, defaultFormatter: (value: number) => string) => string | null | undefined;
  /**
   * Determines whether the labels are placed before or after the ticks.
   *
   * @default "end"
   */
  accessor labelPlacement: "end" | "start";
  /**
   * Determines the layout/orientation of the ticks component. By default, the ticks will render horizontally.
   * When set to `vertical`, the ticks will render vertically.
   *
   * @default "horizontal"
   */
  accessor layout: Layout;
  /**
   * The component's maximum rendered value.
   *
   * @default 100
   */
  accessor max: number;
  /**
   * The component's minimum rendered value.
   *
   * @default 0
   */
  accessor min: number;
  /**
   * When `true`, the values are displayed from high to low.
   *
   * @default false
   */
  accessor mirrored: boolean;
  /**
   * The manner in which ticks are positioned along the component. It determines how [values](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-ticks/#values) is interpreted.
   *
   * - `count`: Places a fixed number of ticks (specified in [values](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-ticks/#values)) at equal intervals.
   * - `percent`: Interprets [values](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-ticks/#values) as percentages. If it's a single number, that number is the interval between ticks; if it's an array, the array specifies the percentage positions for ticks.
   * - `value`: Places ticks only at the values listed in [values](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-ticks/#values).
   *
   * @default "count"
   * @example
   * ```html
   * <!-- Place ticks at each value listed in `values` -->
   * <arcgis-slider min="0" max="100" show-range-labels values="20, 50">
   *   <arcgis-ticks
   *     slot="content-end" style="flex:1;"
   *     min="0" max="100"
   *     show-labels label-placement="end"
   *     mode="value"
   *     values="0, 10, 20, 30, 40, 50, 60, 70, 80, 90, 100">
   *   </arcgis-ticks>
   * </arcgis-slider>
   * ```
   * @example
   * In count mode, the [values](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-ticks/#values) property specifies the number of ticks to render (not a list of tick values).
   * For example, use `11` ticks to show 0–100 in intervals of 10 (0, 10, 20, ..., 100).
   * ```html
   * <!-- 11 ticks from 0 to 100 -->
   * <arcgis-slider min="0" max="100" show-range-labels values="20, 50">
   *   <arcgis-ticks
   *     slot="content-end" style="flex:1;"
   *     min="0" max="100"
   *     show-labels label-placement="end"
   *     mode="count"
   *     values="11">
   *   </arcgis-ticks>
   * </arcgis-slider>
   * ```
   * @example
   * In percent mode, values are percentages along the track.
   * Use an array to place ticks at specific percentages, or a single number as a repeating interval.
   * ```html
   * <!-- Ticks at 0%, 25%, 50%, 75%, and 100% -->
   * <arcgis-slider min="0" max="200" show-range-labels values="50, 150">
   *   <arcgis-ticks
   *     slot="content-end" style="flex:1;"
   *     min="0" max="200"
   *     show-labels label-placement="end"
   *     mode="percent"
   *     values="0, 25, 50, 75, 100">
   *   </arcgis-ticks>
   * </arcgis-slider>
   * ```
   * @see [values](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-ticks/#values)
   */
  accessor mode: TickMode;
  /**
   * Indicates whether to render a line connecting the ticks.
   *
   * @default false
   */
  accessor showBaseline: boolean;
  /**
   * Indicates whether to render labels for the ticks.
   *
   * @default false
   */
  accessor showLabels: boolean;
  /**
   * Indicates where ticks are rendered along the component. This can be set as comma-separated
   * numbers in the attribute (e.g., `<arcgis-ticks values="10, 20, 30"></arcgis-ticks>`) or programmatically as
   * either a single number or an array of numbers (e.g., `ticks.values = 10`, `ticks.values = [10, 20, 30]`).
   * See the description for [mode](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-ticks/#mode) for more information about how this property is interpreted by each mode.
   *
   * @see [mode](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-ticks/#mode)
   */
  accessor values: TickValues;
  /**
   * Fires when the user clicks on one of the ticks. This event is only emitted when the [interactive](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-ticks/#interactive) property is set to `true`.
   *
   * @see [interactive](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-ticks/#interactive)
   * @example
   * The following example listens for the `arcgisTickClick` event and logs the clicked tick's value.
   * ```js
   * const ticks = document.querySelector("arcgis-ticks");
   * ticks.addEventListener("arcgisTickClick", (event) => {
   *   console.log("Clicked tick value:", event.detail.value);
   * });
   * ```
   */
  readonly arcgisTickClick: import("@arcgis/lumina").TargetedEvent<this, { value: number; }>;
  readonly "@eventTypes": {
    arcgisTickClick: ArcgisTicks["arcgisTickClick"]["detail"];
  };
}