@arcgis/common-components 5.1.0-next.4 → 5.1.0-next.41

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

@@ -1,35 +1,73 @@
 /// <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,
+ * 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:
+ * ```html
+ * <arcgis-slider min="0" max="100" show-range-labels value-labels-display="always" steps="1" value-labels-placement="start">
+ *   <arcgis-ticks interactive slot="content-end" style="flex:1;" min="0" max="100" mode="count" values="11" show-labels>
+ *   </arcgis-ticks>
+ * </arcgis-slider>
+ * ```
+ *
+ * > ### Which slider should you use: `arcgis-slider` or `calcite-slider`?
+ * >
+ * > It is recommended to use [`calcite-slider`](https://developers.arcgis.com/calcite-design-system/components/slider/) for most use cases, as the component
+ * > offers a consistent UI/UX and accommodates the majority of implementations.
+ * >
+ * > Use `arcgis-slider` for advanced use cases, where solutions seek the following:
+ * >
+ * > * [layout](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#layout): configurations, where `arcgis-slider` offers a `layout` of `"vertical"`.
+ * > * Display more than two values in the component.
+ * > * A custom range display, where `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.
+ * > * Additional slot configurations for adding elements within or over the component, where `arcgis-slider` can slot
+ * >   content using the `content-start`, `content-end`, and `popover` slots.
+ *
  * @slot [content-start] - A slot for elements before the track.
  * @slot [content-end] - A slot for elements after the track.
  * @slot [popover] - A slot for custom content to be rendered in the popover.
+ * @since 5.0
  */
 export abstract class ArcgisSlider extends LitElement {
   /**
-   * The currently active value of the slider.
+   * The active value of the slider, based on which thumb or range (segment) is active. This returns the stored value for the active thumb,
+   * so it may reflect the thumb’s last set position.
    *
-   * It can be:
+   *
+   * It returns
    * - `undefined` when no value is active
    * - a `number` when a single value is active
-   * - `"all"` when the range is active
+   * - `"all"` when the range (segment) is active
    *
-   * Listen to `arcgisActiveValueChange` to be notified when a value becomes active or inactive.
+   * Listen to [@arcgisActiveValueChange](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#event-arcgisActiveValueChange) to be notified when a value becomes active or inactive.
    *
-   * @see [arcgisActiveValueChange](#arcgisActiveValueChange)
+   * @see [@arcgisActiveValueChange](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#event-arcgisActiveValueChange)
    */
   get activeValue(): number | "all" | undefined;
   /**
-   * When `true`, allows the slider's values to overlap.
+   * When `true`, allows multiple thumbs to overlap by sharing the same value.
+   * When `false`, thumbs are prevented from overlapping.
    *
    * @default false
    */
   accessor allowValuesOverlap: boolean;
-  /** @default false */
+  /**
+   * If true, the component will not be destroyed automatically when it is
+   * disconnected from the document. This is useful when you want to move the
+   * component to a different place on the page, or temporarily hide it. If this
+   * is set, make sure to call the [destroy()](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#destroy) method when you are done to
+   * prevent memory leaks.
+   *
+   * @default false
+   */
   accessor autoDestroyDisabled: boolean;
   /**
    * Indicates whether the slider is disabled.
@@ -38,63 +76,106 @@ export abstract class ArcgisSlider extends LitElement {
    */
   accessor disabled: boolean;
   /**
-   * Used to configure where the fill is placed along the slider track in relation to the value handle.
-   *
-   * Range mode will always display the fill between the min and max handles.
+   * Controls where the filled segment is displayed on the track for single-thumb sliders.
+   * Range sliders always display the fill between the min and max thumbs.
    *
    * @default "start"
    */
   accessor fillPlacement: "end" | "none" | "start";
   /**
-   * Used to define the full range displayed by the slider.
+   * Sets the maximum value of the slider display full 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).
    *
-   * The full range is visualized by the track while the [min](#min) and [max](#max) defines the subset of allowed values for the thumbs.
+   * The `fullRangeMax` must be greater than or equal to [max](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#max) property of the slider.
    *
-   * @see [fullRangeMin](#fullRangeMin)
+   * @see [fullRangeMin](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#fullRangeMin)
    * @example
-   * Slider with a full range from 0 to 100, while only allowing thumb values between 25 and 75.
    * ```html
+   * <!-- Slider with a full range from 0 to 100, while only allowing thumb values between 25 and 75. -->
    * <arcgis-slider full-range-min="0" full-range-max="100" min="25" max="75" values="50"></arcgis-slider>
    * ```
    */
   accessor fullRangeMax: number | undefined;
   /**
-   * Used to define the full range displayed by the slider.
+   * Sets the minimum value of the slider display full 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).
    *
-   * The full range is visualized by the track while the [min](#min) and [max](#max) defines the subset of allowed values for the thumbs.
+   * The `fullRangeMin` must be less than or equal to [min](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#min) property of the slider.
    *
-   * @see [fullRangeMax](#fullRangeMax)
+   * @see [fullRangeMax](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#fullRangeMax)
    * @example
-   * Slider with a full range from 0 to 100, while only allowing thumb values between 25 and 75.
    * ```html
+   * <!-- Slider with a full range from 0 to 100, while only allowing thumb values between 25 and 75. -->
    * <arcgis-slider full-range-min="0" full-range-max="100" min="25" max="75" values="50"></arcgis-slider>
    * ```
    */
   accessor fullRangeMin: number | undefined;
   /**
-   * When specified, allows users to customize labels.
+   * Controls how many "small" keyboard increments are applied in order to move a thumb or range faster using the
+   * keyboard. The following keys are considered "large" increment keys:
+   *
+   * - PageUp/PageDown
+   * - Shift + Arrow keys
+   *
+   * @default 10
+   * @internal
+   */
+  accessor keyboardLargeStep: number;
+  /**
+   * Allows customizing how slider labels are formatted for [min](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#min), [max](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#max), and thumb values.
+   * The formatted value is used for the visible labels and for the thumb’s accessible value text via `aria-valuetext`.
+   * Return `null` or `undefined` to use the default formatting.
    *
-   * Note: the formatted label is also used as the thumb's accessible value text
-   * via `aria-valuetext`, which screen readers prefer to announce over the raw
-   * numeric value.
+   * @example
+   * ```js
+   * // Format labels to use "K" for thousands and "M" for millions
+   * // and use "start" and "end" for min and max labels respectively.
+   * slider.labelFormatter = (value, type, defaultFormatter) => {
+   *   if (type === "min") return "start";
+   *   if (type === "max") return "end";
+   *   if (type !== "value") return defaultFormatter(value);
+   *
+   *   const abs = Math.abs(value);
+   *   if (abs >= 1_000_000) {
+   *     const num = (value / 1_000_000).toLocaleString(undefined, { maximumSignificantDigits: 3 });
+   *     return `${num} M`;
+   *   }
+   *
+   *   if (abs >= 1_000) {
+   *     const num = (value / 1_000).toLocaleString(undefined, { maximumSignificantDigits: 3 });
+   *     return `${num} K`;
+   *   }
+   *   return defaultFormatter(value);
+   * };
+   * ```
    */
-  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 widget.
+   * 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.
    *
    * @default "horizontal"
+   * @see [mirrored](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#mirrored)
    */
   accessor layout: "horizontal" | "vertical";
   /**
-   * The maximum possible data/thumb value of the slider.
+   * The maximum value for the slider thumbs. Thumbs will not move past this value.
    *
-   * To display the `max` value's label on the slider, set [showRangeLabels](#showRangeLabels) to `true`.
-   * To allow the end user to modify the max value, set [rangeLabelsEditingEnabled](#rangeLabelsEditingEnabled) to `true`.
+   * To display the `max` label on the slider, set [showRangeLabels](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#showRangeLabels) to `true`.
+   * To allow the end user to modify the `max` value, set [rangeLabelsEditingEnabled](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#rangeLabelsEditingEnabled) to `true`.
    *
-   * @see [rangeLabelsEditingEnabled](#rangeLabelsEditingEnabled)
-   * @see [showRangeLabels](#showRangeLabels)
+   * @see [rangeLabelsEditingEnabled](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#rangeLabelsEditingEnabled)
+   * @see [showRangeLabels](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#showRangeLabels)
+   * @see [fullRangeMax](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#fullRangeMax)
    */
   accessor max: number;
+  /**
+   * Replace localized message strings with your own strings.
+   *
+   * _**Note**: Individual message keys may change between releases._
+   */
   accessor messageOverrides: {
       componentLabel?: string | undefined;
       maximumValue?: string | undefined;
@@ -120,33 +201,59 @@ export abstract class ArcgisSlider extends LitElement {
       sliderValue: string;
   }>;
   /**
-   * The minimum possible data/thumb value of the slider.
+   * The minimum value for the slider thumbs. Thumbs will not move past this value.
+   * To display the `min` label on the slider, set [showRangeLabels](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#showRangeLabels) to `true`.
+   * To allow the end user to modify the `min` value, set [rangeLabelsEditingEnabled](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#rangeLabelsEditingEnabled) to `true`.
    *
-   * To display the `min` value's label on the slider, set [showRangeLabels](#showRangeLabels) to `true`.
-   * To allow the end user to modify the min value, set [rangeLabelsEditingEnabled](#rangeLabelsEditingEnabled) to `true`.
-   *
-   * @see [rangeLabelsEditingEnabled](#rangeLabelsEditingEnabled)
-   * @see [showRangeLabels](#showRangeLabels)
+   * @see [rangeLabelsEditingEnabled](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#rangeLabelsEditingEnabled)
+   * @see [showRangeLabels](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#showRangeLabels)
    */
   accessor min: number;
   /**
-   * When `true`, the slider will display values from high to low.
+   * When `true`, the slider will display values from high to low. This inverts the direction of the slider.
    *
    * @default false
+   * @see [layout](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#layout)
    */
   accessor mirrored: boolean;
   /**
-   * The accessible label of the popover.
+   * The accessible label for the popover. This label is used by assistive technologies and does not affect the visible UI.
    *
    * @default ""
+   * @see [Calcite popover](https://developers.arcgis.com/calcite-design-system/components/popover/#api-reference-properties-label)
    */
   accessor popoverLabel: Popover["label"];
   /**
-   * Determines the placement of the popover relative to the track.
+   * Determines which side of the track the popover is placed on.
+   * The popover is the floating container that displays the content from the `popover` slot.
+   * * `"start"`: Positions the popover above a horizontal slider or to the left of a vertical slider.
+   * * `"end"`: Positions the popover below a horizontal slider or to the right of a vertical slider.
    *
-   * @default "leading"
+   * @default "start"
+   * @example
+   * ```js
+   * const slider = document.querySelector("arcgis-slider");
+   * slider.popoverPlacement = "end";
+   *
+   * // Example: Dynamic popover content based on slider value
+   * const popover = document.getElementById("popover");
+   * const unitCost = 12.5;
+   * const numberFormatter = new Intl.NumberFormat();
+   * const usd = new Intl.NumberFormat(undefined, { style: "currency", currency: "USD" });
+   *
+   * const renderPopover = () => {
+   *   const value = Number(slider.values?.[0] ?? 0); // 0-100
+   *   const annualCost = (value / 100) * 800 * 365 * unitCost;
+   *   popover.textContent = `Est. annual cost: ${usd.format(annualCost)} (at ${numberFormatter.format(value)}%)`;
+   *   slider.popoverLabel = `Cost estimate ${usd.format(annualCost)} at ${numberFormatter.format(value)} percent`;
+   * };
+   *
+   * slider.addEventListener("arcgisInput", renderPopover);
+   * slider.addEventListener("arcgisChange", renderPopover);
+   * renderPopover();
+   * ```
    */
-  accessor popoverPlacement: "leading" | "trailing";
+  accessor popoverPlacement: "end" | "start";
   /**
    * Defines how slider thumb values should be rounded. This number indicates the number
    * of decimal places slider thumb _values_ should round to when they have been moved.
@@ -162,34 +269,36 @@ export abstract class ArcgisSlider extends LitElement {
    * The labels of the thumbs will display two decimal places, but the precision of the actual
    * thumb values will not be lost even when the user slides or moves the thumb.
    *
-   * Keep in mind this property rounds thumb [values](#values) and shouldn't be used exclusively
-   * for formatting purposes. To format thumb `labels`, use the [labelFormatter](#labelFormatter)
+   * Keep in mind this property rounds thumb [values](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#values) and shouldn't be used exclusively
+   * for formatting purposes. To format thumb `labels`, use the [labelFormatter](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#labelFormatter)
    * property.
    *
    * @default 4
    * @example
-   * // thumb label will display 50.43
-   * // thumb value will maintain precision, so value will remain at 50.4331
    * ```html
+   * <!-- thumb label will display 50.43 -->
+   * <!-- thumb value will maintain precision, so value will remain at 50.4331 -->
    * <arcgis-slider min="0" max="100" values="50.4331" precision="4"></arcgis-slider>
    * ```
    */
   accessor precision: number;
   /**
-   * Indicates whether to enable editing range values via keyboard input
-   * when the user clicks a [min](#min) or [max](#max) label.
-   * This allows the user to increase or decrease the data range of the slider.
+   * When `true`, users can edit 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) range labels via keyboard input.
+   * Editing these labels updates the slider’s interactive range.
    *
    * @default false
    */
   accessor rangeLabelsEditingEnabled: boolean;
   /**
-   * Determines whether the range labels are placed centered with the slider track
-   * or placed below it when the [layout](#layout) is `"horizontal"`.
+   * Controls where 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) range labels are positioned relative to the track.
+   * 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.
    *
    * @default "center"
    */
-  accessor rangeLabelsPlacement: "center" | "trailing";
+  accessor rangeLabelsPlacement: "center" | "end";
   /**
    * Indicates if the user can drag the segment between thumbs to update thumb positions.
    *
@@ -197,7 +306,7 @@ export abstract class ArcgisSlider extends LitElement {
    */
   accessor segmentsDraggingDisabled: boolean;
   /**
-   * Indicates whether to min and max range labels are visible on the slider.
+   * 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.
    *
    * @default false
    */
@@ -212,24 +321,24 @@ export abstract class ArcgisSlider extends LitElement {
    * 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](#min) is `0` and the slider [max](#max) is `10`, then the user will
+   * [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.
    *
    * @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.
+   * <!-- set steps at an interval of 0.5. So the -->
+   * <!-- slider thumb snaps at values of 0.5, 1.0, 1.5, etc. -->
    * <arcgis-slider min="0" max="10" steps="0.5" values="5"></arcgis-slider>
    * ```
    * @example
    * ```html
-   * // Set steps at specific slider positions
+   * <!-- 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>
    * ```
    */
   accessor steps: number[] | number | undefined;
   /**
-   * Indicates whether to show the value labels on the slider.
+   * Controls when thumb value labels are displayed.
    *
    * This property can be set to one of the following values:
    * - `"always"`: Always show the labels.
@@ -241,49 +350,135 @@ export abstract class ArcgisSlider extends LitElement {
   accessor valueLabelsDisplay: "always" | "auto" | "hidden";
   /**
    * Indicates whether to enable editing input values via keyboard input
-   * when the user clicks a label. This allows the user to move the slider
+   * 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.png)
    *
    * @default false
    */
   accessor valueLabelsEditingEnabled: boolean;
   /**
-   * Determines whether the labels are placed before or after the track.
+   * Determines whether the thumb value labels are placed before or after the track.
    *
-   * @default "leading"
+   * @default "start"
    */
-  accessor valueLabelsPlacement: "leading" | "trailing";
+  accessor valueLabelsPlacement: "end" | "start";
   /** An array of numbers representing absolute thumb positions on the slider. */
   accessor values: number[];
+  /** Permanently destroys the component. */
   destroy(): Promise<void>;
   /**
-   * Fires when the `activeValue` changes because a
-   * thumb or range is focused and blurred.
-   *
-   * This event does not fire when `values` changes.
-   * Use `arcgisInput` or `arcgisChange` instead.
+   * Fires when the [activeValue](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#activeValue) changes as a thumb or the range gains or loses focus.
+   * This event does not fire when [values](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#values) change. Use [@arcgisInput](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#event-arcgisInput) for continuous updates or
+   * [@arcgisChange](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#event-arcgisChange) when the interaction is committed.
    *
-   * @see [activeValue](#activeValue)
+   * @example
+   * ```js
+   * // Display the active value status of the slider in a div element
+   * const slider = document.querySelector("arcgis-slider");
+   * const status = document.getElementById("slider-status");
+   *
+   * const renderActive = () => {
+   *   const active = slider.activeValue;
+   *   // active is: undefined (none), number (thumb value), or "all" (range segment)
+   *   status.textContent =
+   *     active === "all"
+   *       ? "Editing range"
+   *       : active == null
+   *         ? "No active thumb"
+   *         : `Editing value: ${active}`;
+   * };
+   *
+   * slider.addEventListener("arcgisActiveValueChange", renderActive);
+   * // Pair with these when you need value updates:
+   * slider.addEventListener("arcgisInput", () => console.log("values", slider.values));
+   * slider.addEventListener("arcgisChange", () => console.log("committed", slider.values));
+   *
+   * renderActive();
+   * ```
+   * @see [activeValue](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#activeValue)
    */
   readonly arcgisActiveValueChange: import("@arcgis/lumina").TargetedEvent<this, void>;
   /**
    * Fires when the thumb or range is released on the component.
    *
-   * Note: To constantly listen to the drag event,
-   * use `arcgisInput` instead.
+   * Use [@arcgisInput](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-slider/#event-arcgisInput) for continuous updates during a drag.
+   *
+   * @example
+   * ```js
+   * const slider = document.querySelector("arcgis-slider");
+   * slider.popoverPlacement = "end";
+   *
+   * // Example: Dynamic popover content based on slider value
+   * const popover = document.getElementById("popover");
+   * const unitCost = 12.5;
+   * const numberFormatter = new Intl.NumberFormat();
+   * const usd = new Intl.NumberFormat(undefined, { style: "currency", currency: "USD" });
+   *
+   * const renderPopover = () => {
+   *   const value = Number(slider.values?.[0] ?? 0); // 0-100
+   *   const annualCost = (value / 100) * 800 * 365 * unitCost;
+   *   popover.textContent = `Est. annual cost: ${usd.format(annualCost)} (at ${numberFormatter.format(value)}%)`;
+   *   slider.popoverLabel = `Cost estimate ${usd.format(annualCost)} at ${numberFormatter.format(value)} percent`;
+   * };
+   *
+   * slider.addEventListener("arcgisChange", renderPopover);
+   * renderPopover();
+   * ```
    */
   readonly arcgisChange: import("@arcgis/lumina").TargetedEvent<this, void>;
   /**
-   * Fires when the thumb or range is being dragged and released on the component.
+   * Fires continuously while the thumb or range is being dragged.
+   * This event can fire frequently; consider debouncing or throttling expensive work.
    *
-   * Note: Fires frequently during drag. To perform
-   * expensive operations consider using a debounce or throttle to avoid
-   * locking up the main thread.
+   * @example
+   * ```js
+   * import FeatureEffect from "@arcgis/core/layers/support/FeatureEffect";
+   * import FeatureFilter from "@arcgis/core/layers/support/FeatureFilter";
+   *
+   * slider.addEventListener("arcgisInput", () => {
+   *   const value = slider.values[0] ?? 0;
+   *   layer.featureEffect = new FeatureEffect({
+   *      filter: new FeatureFilter({
+   *        where: `FIELD <= ${value}`,
+   *      }),
+   *     includedEffect: "bloom(1.4, 0.2px, 0.1)",
+   *     excludedEffect: "opacity(20%) grayscale(100%)",
+   *   });
+   * });
+   * ```
    */
   readonly arcgisInput: import("@arcgis/lumina").TargetedEvent<this, void>;
-  /** Fires when the min or max values are changed by the user. */
+  /**
+   * 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.
+   * 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
+   * ```js
+   * // Example: Keep a "budget" value inside the editable min/max range
+   * const slider = document.querySelector("arcgis-slider");
+   *
+   * const clamp = (val, min, max) => Math.min(max, Math.max(min, val));
+   *
+   * const render = () => {
+   *   rangeText.textContent = `Allowed: ${slider.min}–${slider.max}`;
+   *
+   *   // If your UI stores a single value, keep it inside the new range.
+   *   const current = Number(slider.values?.[0] ?? slider.min);
+   *   const next = clamp(current, slider.min, slider.max);
+   *
+   *   if (next !== current) {
+   *     slider.values = [next];
+   *   }
+   *
+   *   valueText.textContent = `Selected: ${next}`;
+   * };
+   *
+   * slider.addEventListener("arcgisRangeChange", render);
+   * render();
+   * ```
+   */
   readonly arcgisRangeChange: import("@arcgis/lumina").TargetedEvent<this, void>;
   readonly "@eventTypes": {
     arcgisActiveValueChange: ArcgisSlider["arcgisActiveValueChange"]["detail"];