@arcgis/common-components 5.1.0-next.1 → 5.1.0-next.100

package/dist/components/arcgis-picker-input/customElement.js

@@ -1,18 +1,18 @@
 /* COPYRIGHT Esri - https://js.arcgis.com/5.1/LICENSE.txt */
-import { c as s } from "../../chunks/runtime.js";
-import { css as n, html as o } from "lit";
-import { LitElement as l, createEvent as i, safeStyleMap as a } from "@arcgis/lumina";
-import { createRef as r, ref as t } from "lit/directives/ref.js";
-const c = n`:host{display:flex}:host([disabled]){opacity:.25;pointer-events:none}button{overflow:hidden;background-color:transparent;align-items:center;border:none;border-radius:0;box-sizing:border-box;cursor:pointer;display:flex;font-family:inherit;gap:var(--calcite-space-sm);height:100%;justify-content:center;outline-color:transparent;outline-offset:0;padding:3px 0;padding-inline:3px var(--calcite-space-sm);position:relative;text-decoration:none;user-select:none;text-align:center;-webkit-appearance:none;width:100%;&:focus{outline:var(--calcite-border-width-md) solid var(--calcite-color-brand);outline-offset:var(--calcite-border-width-md)}&:hover{text-decoration:none}}.preview{border:var(--calcite-border-width-sm) solid #949494;display:flex;align-items:center;flex-grow:1}.container{display:flex;gap:5px;width:100%}::slotted([slot="preview"]){flex-grow:1;display:flex}calcite-icon{color:var(--calcite-color-text-3)}`;
-class p extends l {
+import { c as n } from "../../chunks/runtime.js";
+import { css as l, html as o } from "lit";
+import { LitElement as a, createEvent as i, safeStyleMap as r } from "@arcgis/lumina";
+import { createRef as c, ref as t } from "lit/directives/ref.js";
+const p = l`:host{display:flex}:host([disabled]){opacity:.25;pointer-events:none}button{overflow:hidden;background-color:transparent;align-items:center;border:none;border-radius:0;box-sizing:border-box;cursor:pointer;display:flex;font-family:inherit;gap:var(--calcite-space-sm);height:100%;justify-content:center;outline-color:transparent;outline-offset:0;padding:3px 0;padding-inline:3px var(--calcite-space-sm);position:relative;text-decoration:none;user-select:none;text-align:center;-webkit-appearance:none;width:100%;&:focus{outline:var(--calcite-border-width-md) solid var(--calcite-color-brand);outline-offset:var(--calcite-border-width-md)}&:hover{text-decoration:none}}.preview{border:var(--calcite-border-width-sm) solid #949494;display:flex;align-items:center;flex-grow:1}.container{display:flex;gap:5px;width:100%}::slotted([slot="preview"]){flex-grow:1;display:flex}calcite-icon{color:var(--calcite-color-text-3)}`;
+class d extends a {
   constructor() {
-    super(), this.panelEl = r(), this.open = !1, this.disabled = !1, this.iconEnd = "pencil", this.label = "", this.arcgisPopoverOpen = i(), this.arcgisPopoverClose = i(), this.listenOn(document.body, "arcgisPopoverOpen", this.onPopoverOpen);
+    super(), this.panelEl = c(), this.open = !1, this.disabled = !1, this.iconEnd = "pencil", this.label = "", this.arcgisPopoverOpen = i(), this.arcgisPopoverClose = i(), this.listenOn(document.body, "arcgisPopoverOpen", this.onPopoverOpen);
   }
   static {
     this.properties = { open: 16, disabled: 7, heading: 1, iconEnd: 1, intlDone: 1, label: 1, popoverProps: 0 };
   }
   static {
-    this.styles = c;
+    this.styles = p;
   }
   async close() {
     this.onPopoverClose();
@@ -48,10 +48,10 @@ class p extends l {
   }
   render() {
     const { popoverProps: e } = this;
-    return o`<calcite-popover pointer-disabled trigger-disabled @keyup=${this.handlePopoverKeyUp} .label=${this.label} .offsetDistance=${e?.offsetDistance ?? 0} .offsetSkidding=${e?.offsetSkidding ?? 0} .flipDisabled=${e?.flipDisabled ?? !1} .open=${this.disabled ? !1 : this.open} .overlayPositioning=${e?.overlayPositioning ?? "fixed"} .placement=${e?.placement ?? "bottom"} @calcitePopoverOpen=${this.handlePopoverOpen} .referenceElement=${e?.refElement ?? this.previewContainerEl}><calcite-panel closable .heading=${this.heading} style=${a(e?.maxHeight ? { maxHeight: e.maxHeight } : void 0)} @calcitePanelClose=${this.handlePanelClose} ${t(this.panelEl)}><slot name=content></slot><calcite-button appearance=solid slot=footer width=full .label=${this.intlDone} @click=${this.onPopoverClose}>${this.intlDone}</calcite-button></calcite-panel></calcite-popover><div class="container"><div class="preview" ${t(this.setPreviewContainerRef)}><button .disabled=${this.disabled} @click=${this.handleButtonClick} type=button .ariaLabel=${this.label} ${t(this.setButtonRef)}><slot name=preview></slot>${this.iconEnd ? o`<calcite-icon .icon=${this.iconEnd} scale=s></calcite-icon>` : null}</button></div><slot name=content-end></slot></div>`;
+    return o`<calcite-popover pointer-disabled trigger-disabled @keyup=${this.handlePopoverKeyUp} .label=${this.label} .offsetDistance=${e?.offsetDistance ?? 0} .offsetSkidding=${e?.offsetSkidding ?? 0} .flipDisabled=${e?.flipDisabled ?? !1} .open=${this.disabled ? !1 : this.open} .overlayPositioning=${e?.overlayPositioning ?? "fixed"} .placement=${e?.placement ?? "bottom"} @calcitePopoverOpen=${this.handlePopoverOpen} @calcitePopoverClose=${(s) => s.stopPropagation()} .referenceElement=${e?.refElement ?? this.previewContainerEl}><calcite-panel closable .heading=${this.heading} style=${r(e?.maxHeight ? { maxHeight: e.maxHeight } : void 0)} @calcitePanelClose=${this.handlePanelClose} ${t(this.panelEl)}><slot name=content></slot><calcite-button appearance=solid slot=footer width=full .label=${this.intlDone} @click=${this.onPopoverClose}>${this.intlDone}</calcite-button></calcite-panel></calcite-popover><div class="container"><div class="preview" ${t(this.setPreviewContainerRef)}><button .disabled=${this.disabled} @click=${this.handleButtonClick} type=button .ariaLabel=${this.label} ${t(this.setButtonRef)}><slot name=preview></slot>${this.iconEnd ? o`<calcite-icon .icon=${this.iconEnd} scale=s></calcite-icon>` : null}</button></div><slot name=content-end></slot></div>`;
   }
 }
-s("arcgis-picker-input", p);
+n("arcgis-picker-input", d);
 export {
-  p as ArcgisPickerInput
+  d as ArcgisPickerInput
 };

package/dist/components/arcgis-ramp-color/customElement.d.ts

@@ -2,6 +2,7 @@
 import type Color from "@arcgis/core/Color.js";
 import type { PublicLitElement as LitElement } from "@arcgis/lumina";
 
+/** @internal */
 export abstract class ArcgisRampColor extends LitElement {
   /** @default "horizontal" */
   accessor layout: "horizontal" | "vertical";
@@ -12,6 +13,7 @@ export abstract class ArcgisRampColor extends LitElement {
   accessor stops: ColorStop[];
 }
 
+/** @internal */
 export interface ColorStop {
   color: Color | string;
   value: number;

package/dist/components/arcgis-ramp-color-break/customElement.d.ts

@@ -3,6 +3,7 @@ import type Color from "@arcgis/core/Color.js";
 import type { PublicLitElement as LitElement } from "@arcgis/lumina";
 import type { ArcgisRampColor } from "../arcgis-ramp-color/customElement.js";
 
+/** @internal */
 export abstract class ArcgisRampColorBreak extends LitElement {
   /** @default "horizontal" */
   accessor layout: ArcgisRampColor["layout"];
@@ -13,6 +14,7 @@ export abstract class ArcgisRampColorBreak extends LitElement {
   accessor stops: ColorBreak[];
 }
 
+/** @internal */
 export interface ColorBreak {
   color: Color | string;
   max: number;

package/dist/components/arcgis-ramp-opacity/customElement.d.ts

@@ -3,6 +3,7 @@ import type Color from "@arcgis/core/Color.js";
 import type { PublicLitElement as LitElement } from "@arcgis/lumina";
 import type { ArcgisRampColor } from "../arcgis-ramp-color/customElement.js";
 
+/** @internal */
 export abstract class ArcgisRampOpacity extends LitElement {
   accessor fillColor: Color | string;
   /** @default "horizontal" */

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

@@ -1,35 +1,71 @@
 /// <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 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:
+ * ```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>
+ * ```
+ *
+ * > [!TIP]
+ * > Which slider should you use: `arcgis-slider` or `calcite-slider`?
+ * >
+ * > 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.
+ * >
+ * > 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.
  * @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 +74,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'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).
    *
-   * 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'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).
    *
-   * 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:
    *
-   * 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.
+   * - 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.
+   *
+   * @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 +199,59 @@ export abstract class ArcgisSlider extends LitElement {
       sliderValue: string;
   }>;
   /**
-   * The minimum possible data/thumb value of the slider.
-   *
-   * 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`.
+   * 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`.
    *
-   * @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 +267,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 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,39 +304,41 @@ export abstract class ArcgisSlider extends LitElement {
    */
   accessor segmentsDraggingDisabled: boolean;
   /**
-   * Indicates whether to min and 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](#min) is `0` and the slider [max](#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;
   /**
-   * 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,139 @@ 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.avif)
    *
    * @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: "end" | "start";
+  /**
+   * 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 valueLabelsPlacement: "leading" | "trailing";
-  /** 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.
+   * 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.
    *
-   * Note: To constantly listen to the drag event,
-   * use `arcgisInput` instead.
+   * @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 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"];