@arcgis/common-components 5.1.0-next.13 → 5.1.0-next.131

package/dist/components/arcgis-slider/customElement.d.ts

@@ -1,13 +1,12 @@
 /// <reference path="../../index.d.ts" />
-/// <reference types="@arcgis/core/interfaces.d.ts" />
 import type { PublicLitElement as LitElement } from "@arcgis/lumina";
 import type { T9nMeta } from "@arcgis/lumina/controllers";
 import type { Popover as Popover } from "@esri/calcite-components/components/calcite-popover";
 
 /**
- * The Slider component is used to filter data or collect numeric input from users. It supports single or multiple thumbs, configured via the
- * [values](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#values) property. The Slider can be displayed in horizontal or vertical [layout](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#layout), supports snapping to defined [steps](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#steps),
- * configurable value [precision](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#precision), and custom [labelFormatter](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#labelFormatter). It also includes keyboard interaction,
+ * The slider component is used to filter data or collect numeric input from users. It supports single or multiple thumbs, configured via the
+ * [values](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#values) property. The slider can be displayed in a horizontal or vertical [layout](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#layout), and it supports snapping to defined [steps](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#steps),
+ * configurable value [precision](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#precision), and a custom [labelFormatter](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#labelFormatter). It also includes keyboard interaction,
  * optional editable labels, and customizable popover content.
  *
  * The slider component can be set up with the [arcgis-ticks](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-ticks/) component. See the example below:
@@ -18,17 +17,17 @@ import type { Popover as Popover } from "@esri/calcite-components/components/cal
  * </arcgis-slider>
  * ```
  *
- * ### Which slider should you use: arcgis-slider or calcite-slider?
+ * > [!TIP]
+ * > Which slider should you use: `arcgis-slider` or `calcite-slider`?
  * >
- * > In general, use [calcite-slider](https://developers.arcgis.com/calcite-design-system/components/slider/) over `arcgis-slider`.
- * > It covers common slider use cases and works well in most scenarios.
+ * > Use [calcite-slider](https://developers.arcgis.com/calcite-design-system/components/slider/) by default. It provides a consistent UI/UX and supports most common slider use cases.
  * >
- * > Use `arcgis-slider` only when you need functionality that `calcite-slider` does not provide, such as:
- * > * [layout](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#layout): `arcgis-slider` supports `layout="vertical"`.
- * > * Custom range display: `arcgis-slider` supports [fullRangeMin](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#fullRangeMin) and [fullRangeMax](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#fullRangeMax) for displaying a wider
- * > range than the interactive range.
- * > * More than two values: `arcgis-slider` supports an arbitrary number of slider values, beyond single-value or range (two-value) sliders.
- * > * Slot support: Use the `content-start`, `content-end`, and `popover` slots to render custom content before the track, after the track, or inside the popover.
+ * > Choose `arcgis-slider` when you need more advanced behavior, such as:
+ * >
+ * > * A vertical slider via [layout](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#layout).
+ * > * More than two [values](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#values) in a single slider.
+ * > * A display range that extends beyond the interactive range using [fullRangeMin](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#fullRangeMin) and [fullRangeMax](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#fullRangeMax).
+ * > * Additional slotted content using the `content-start`, `content-end`, or `popover` [slots](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#slots).
  *
  * @slot [content-start] - A slot for elements before the track.
  * @slot [content-end] - A slot for elements after the track.
@@ -41,7 +40,7 @@ export abstract class ArcgisSlider extends LitElement {
    * so it may reflect the thumb’s last set position.
    *
    *
-   * It returns
+   * It returns:
    * - `undefined` when no value is active
    * - a `number` when a single value is active
    * - `"all"` when the range (segment) is active
@@ -82,7 +81,7 @@ export abstract class ArcgisSlider extends LitElement {
    */
   accessor fillPlacement: "end" | "none" | "start";
   /**
-   * Sets the maximum value of the slider display full range.
+   * Sets the maximum value of the slider's displayed range.
    * When specified, the slider track is scaled from [fullRangeMin](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#fullRangeMin) to `fullRangeMax`, while
    * the thumbs remain constrained to the interactive range defined by [min](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#min) and [max](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#max).
    *
@@ -97,7 +96,7 @@ export abstract class ArcgisSlider extends LitElement {
    */
   accessor fullRangeMax: number | undefined;
   /**
-   * Sets the minimum value of the slider display full range.
+   * Sets the minimum value of the slider's displayed range.
    * When specified, the slider track is scaled from `fullRangeMin` to [fullRangeMax](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#fullRangeMax), while
    * the thumbs remain constrained to the range defined by [min](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#min) and [max](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#max).
    *
@@ -150,7 +149,7 @@ export abstract class ArcgisSlider extends LitElement {
    * };
    * ```
    */
-  accessor labelFormatter: ((value: number, type: "max" | "min" | "value", defaultFormatter: (value: number) => string) => nullish | string) | undefined;
+  accessor labelFormatter: (value: number, type: "max" | "min" | "value", defaultFormatter: (value: number) => string) => string | null | undefined;
   /**
    * Determines the layout/orientation of the Slider component. By default, the slider will render horizontally with the min value on the left side
    * of the track.
@@ -293,7 +292,7 @@ export abstract class ArcgisSlider extends LitElement {
    * This property only affects the slider when [layout](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#layout) is `"horizontal"`.
    *
    * - `"center"` (default): Places the [min](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#min) and [max](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#max) labels aligned with the track.
-   * - `"end"`: Places the range labels below the the track.
+   * - `"end"`: Places the range labels below the track.
    *
    * @default "center"
    */
@@ -305,34 +304,36 @@ export abstract class ArcgisSlider extends LitElement {
    */
   accessor segmentsDraggingDisabled: boolean;
   /**
-   * Indicates whether to [min](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#min) and [max](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#max) range labels are visible on the slider.
+   * Indicates whether [min](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#min) and [max](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#max) range labels are visible on the slider.
    *
    * @default false
    */
   accessor showRangeLabels: boolean;
   /**
-   * Sets steps, or intervals, on the slider that restrict user
+   * Sets intervals on the slider that restrict user
    * input to specific values. If an array of numbers is passed to this
    * property, the slider thumbs may only be moved to the positions
    * specified in the array.
    *
+   * This can be set as comma-separated numbers in the attribute (e.g., `<arcgis-slider steps="10, 20, 30"></arcgis-slider>`)
+   * or programmatically as either a single number or an array of numbers (e.g., `slider.steps = 10`, `slider.steps = [10, 20, 30]`).
+   *
    * If a single number is set, then steps are set along the entire
-   * slider range at an interval of the provided value. In this scenario,
-   * the user may only slide the thumbs to values at the provided interval.
-   * For example, if a value of `0.5` is set here, and the slider
-   * [min](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#min) is `0` and the slider [max](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#max) is `10`, then the user will
-   * only be able to update the thumbs to values of 0, 0.5, 1.0, 1.5, 2.0, etc.
+   * slider range at an interval of the provided value. The user may
+   * only slide the thumbs to values at the provided interval.
+   * For example, if a value of `0.5` is set and the slider
+   * [min](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#min) is `0` and [max](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#max) is `2`, then the user will
+   * only be able to update the thumbs to values of 0, 0.5, 1.0, 1.5, and 2.0.
    *
    * @example
    * ```html
-   * <!-- set steps at an interval of 0.5. So the -->
-   * <!-- slider thumb snaps at values of 0.5, 1.0, 1.5, etc. -->
+   * <!-- In this example, the thumb snaps to every value evenly divisible by 0.5 between 0 and 10. -->
    * <arcgis-slider min="0" max="10" steps="0.5" values="5"></arcgis-slider>
    * ```
    * @example
    * ```html
-   * <!-- Set steps at specific slider positions -->
-   * <arcgis-slider min="0" max="100" steps="5, 10, 15, 20, 25, 30, 35, 40" values="15, 30"></arcgis-slider>
+   * <!-- In this example, the thumb snaps to the specified values in the steps array (2, 4, 6, and 8). -->
+   * <arcgis-slider min="0" max="10" steps="2, 4, 6, 8" values="4"></arcgis-slider>
    * ```
    */
   accessor steps: number[] | number | undefined;
@@ -352,7 +353,7 @@ export abstract class ArcgisSlider extends LitElement {
    * when the user clicks a thumb value label. This allows the user to move the slider
    * thumb to precise values without sliding the thumbs.
    *
-   * ![Slider with editable labels](https://developers.arcgis.com/javascript/latest/assets/img/apiref/widgets/sliders/slider-edit-label.png)
+   * ![Slider with editable labels](https://developers.arcgis.com/javascript/latest/assets/references/core/widgets/sliders/slider-edit-label.avif)
    *
    * @default false
    */
@@ -363,7 +364,11 @@ export abstract class ArcgisSlider extends LitElement {
    * @default "start"
    */
   accessor valueLabelsPlacement: "end" | "start";
-  /** An array of numbers representing absolute thumb positions on the slider. */
+  /**
+   * An array of numbers representing absolute thumb positions on the slider. This can be set as comma-separated
+   * numbers in the attribute (e.g., `<arcgis-slider values="10, 20, 30"></arcgis-slider>`) or programmatically as an
+   * array of numbers (e.g., `slider.values = [10, 20, 30]`).
+   */
   accessor values: number[];
   /** Permanently destroys the component. */
   destroy(): Promise<void>;
@@ -400,7 +405,7 @@ export abstract class ArcgisSlider extends LitElement {
    */
   readonly arcgisActiveValueChange: import("@arcgis/lumina").TargetedEvent<this, void>;
   /**
-   * Fires when the thumb or range is released on the component.
+   * Fires when the thumb or range is released on the slider.
    *
    * Use [@arcgisInput](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#event-arcgisInput) for continuous updates during a drag.
    *
@@ -450,7 +455,7 @@ export abstract class ArcgisSlider extends LitElement {
    */
   readonly arcgisInput: import("@arcgis/lumina").TargetedEvent<this, void>;
   /**
-   * Fires when the slider's [min](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#min) and [max](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#max) range changes.
+   * Fires when the slider's range changes.
    * This occurs when the user edits the [min](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#min) or [max](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#max) range labels (when enabled).
    *
    * @example