@arcgis/charts-components 5.2.0-next.58 → 5.2.0-next.59

package/dist/chunks/utils.js

@@ -1,21 +1,20 @@
 /* COPYRIGHT Esri - https://js.arcgis.com/5.2/LICENSE.txt */
 import { substitute as b } from "@arcgis/core/intl.js";
-import { w as C, H as j, M as k, T as q, F as M, x as W } from "./index.js";
+import { w as C, H as j, M as q, T as k, F as M, x as W } from "./index.js";
 import { g as $ } from "./series-types.js";
-import { l as E, d as S, q as H, D as U } from "./index3.js";
-import { an as I, ag as K, h as O, c2 as L, a6 as h, c1 as V, aH as P } from "./index2.js";
-import { k as X } from "./index5.js";
+import { l as E, d as S, q as U, D as H } from "./index3.js";
+import { bw as K, ap as I, ag as P, h as O, cs as L, a6 as h, cr as V, aJ as X } from "./index2.js";
 import { q as R, u as f, r as A, p as G } from "./chart-object-literals.js";
 import { d as T } from "./type-guards.js";
-function ae(s, e, i) {
+function se(s, e, i) {
   const t = s?.axes?.[e];
   t?.title !== void 0 ? t.title.content.text = i : t !== void 0 && (t.title = j({
     text: i,
     visible: !0,
-    font: k(q.AxisTitle)
+    font: q(k.AxisTitle)
   }));
 }
-function re(s) {
+function ae(s) {
   const { config: e, layerInfo: i, commonStrings: t, numericFields: a, aggregationType: r } = s;
   let o = "";
   if (e)
@@ -37,67 +36,67 @@ function re(s) {
     }
   return o;
 }
-const B = (s, e, i) => s.axes?.[e] ?? W(i, s.type)[e], D = (s) => {
+const B = (s, e, i) => s.axes?.[e] ?? W(i, s.type)[e], w = (s) => {
   const { config: e, axis: i, axisIndex: t } = s;
   e.axes !== void 0 && (e.axes[t] = i);
-}, oe = (s) => {
+}, re = (s) => {
   const { config: e, axisIndex: i, isMax: t } = s;
   let a = Number.NaN;
   return t ? a = e.axes?.[i]?.maximum : a = e.axes?.[i]?.minimum, a ?? Number.NaN;
 }, N = (s) => {
   const { config: e, value: i, axisIndex: t, isMax: a } = s, r = e?.axes?.[t];
   r !== void 0 && (a ? r.maximum = i : r.minimum = i);
-}, ne = (s) => s.axes?.[0]?.valueFormat ?? M(), le = (s, e, i) => {
+}, oe = (s) => s.axes?.[0]?.valueFormat ?? M(), ne = (s, e, i) => {
   const t = B(s, 0, e);
   if (t !== void 0 && i !== void 0) {
     const a = {
       ...t,
       valueFormat: i
     };
-    D({ config: s, axis: a, axisIndex: 0 });
+    w({ config: s, axis: a, axisIndex: 0 });
   }
-}, ce = (s, e, i) => {
+}, le = (s, e, i) => {
   const t = s.axes?.[e];
   t !== void 0 && (t.integerOnlyValues = i);
-}, Q = (s) => {
+}, J = (s) => {
   const e = $(s.series);
   return e === f.BarSeries || e === f.ComboLineAndBarSeries || e === f.LineSeries;
-}, Y = (s) => {
+}, Q = (s) => {
   const { axisIndex: e, config: i, isMultiAxis: t } = s;
   let a = !1;
-  return e === 0 || e === 1 && t ? a = !0 : e === 2 && (a = Q(i)), a;
-}, ue = (s) => {
+  return e === 0 || e === 1 && t ? a = !0 : e === 2 && (a = J(i)), a;
+}, ce = (s) => {
   const { axisIndex: e, func: i, config: t } = s;
-  return Y({ axisIndex: e, config: t, isMultiAxis: !0 }) ? i(e) : void 0;
+  return Q({ axisIndex: e, config: t, isMultiAxis: !0 }) ? i(e) : void 0;
 }, v = (s, e) => {
   let i;
   const t = e.axes?.[s]?.valueFormat;
-  return (s === 0 || s >= 1 && X(t)) && (i = t), i;
-}, de = (s) => {
+  return (s === 0 || s >= 1 && K(t)) && (i = t), i;
+}, ue = (s) => {
   const { config: e, commonStrings: i, valueFormat: t, axisIndex: a = 0 } = s, r = B(e, a, i);
   if (r !== void 0 && t !== void 0) {
     const o = {
       ...r,
       valueFormat: t
     };
-    D({
+    w({
       config: e,
       axis: o,
       axisIndex: a
     });
   }
-}, fe = (s, e) => s.axes?.[e]?.isLogarithmic ?? !1, ge = (s) => {
+}, de = (s, e) => s.axes?.[e]?.isLogarithmic ?? !1, fe = (s) => {
   const { config: e, isLogarithmic: i, axisIndex: t } = s, a = e.axes?.[t];
   a && (a.isLogarithmic = i, N({ config: e, value: null, axisIndex: t, isMax: !0 }), N({ config: e, value: null, axisIndex: t, isMax: !1 }));
-}, xe = (s) => {
+}, ge = (s) => {
   const { config: e, scrollbar: i, axisIndex: t } = s;
   e.axes?.[t] !== void 0 && (e.axes[t].scrollbar = i);
 };
-async function ye(s) {
-  const { config: e, layer: i, xAxisField: t, splitByField: a, layerFieldsInfo: r, aggregationFields: o, fetchNullValues: u, errorStrings: d } = s, n = r.filter((F) => F.name === a)[0]?.type, x = u !== !0 ? `${a} IS NOT NULL` : "", l = t && u !== !0 ? `${t} IS NOT NULL` : "", { where: m } = e?.dataFilters ?? {}, w = {
+async function xe(s) {
+  const { config: e, layer: i, xAxisField: t, splitByField: a, layerFieldsInfo: r, aggregationFields: o, fetchNullValues: u, errorStrings: d } = s, n = r.filter((F) => F.name === a)[0]?.type, x = u !== !0 ? `${a} IS NOT NULL` : "", l = t && u !== !0 ? `${t} IS NOT NULL` : "", { where: m } = e?.dataFilters ?? {}, D = {
     where: O([m, x, l]),
     // excluding the null values from the list
-    orderByFields: H(a) ? [] : [`${a} ${G.Ascending}`],
+    orderByFields: U(a) ? [] : [`${a} ${G.Ascending}`],
     // default sorting ascending for split-by field
     geometry: e?.dataFilters?.geometry
   };
@@ -112,13 +111,13 @@ async function ye(s) {
       queryObject: i,
       category: e?.series[0].x ?? "",
       splitByField: a,
-      queryConfig: w,
+      queryConfig: D,
       errorStrings: d
     })).keys()
   ) : [];
   if (y = y.slice(0, 500), e) {
-    const F = e?.series.map((c) => P({ where: c.query?.where })?.toString() ?? "").filter((c) => c !== void 0 && c !== "");
-    y = U({
+    const F = e?.series.map((c) => X({ where: c.query?.where })?.toString() ?? "").filter((c) => c !== void 0 && c !== "");
+    y = H({
       arrayA: y,
       arrayB: F,
       getKey: (c) => c === null ? null : c?.toString()
@@ -126,7 +125,7 @@ async function ye(s) {
   }
   return { categoriesArray: y, splitByFieldType: n, numericalField: p };
 }
-function me(s, e) {
+function ye(s, e) {
   let i = e === "";
   for (const t of s)
     if (e === t.name) {
@@ -135,8 +134,8 @@ function me(s, e) {
     }
   return i;
 }
-function pe(s, e) {
-  const i = K(s);
+function me(s, e) {
+  const i = P(s);
   let t = e.length === 0, a = 0;
   for (const r of e) {
     for (const o of i)
@@ -149,7 +148,7 @@ function pe(s, e) {
   }
   return t;
 }
-function Fe(s, e) {
+function pe(s, e) {
   e.forEach((i) => {
     Object.getOwnPropertyNames(i.prototype).forEach((t) => {
       Object.defineProperty(
@@ -160,7 +159,7 @@ function Fe(s, e) {
     });
   });
 }
-async function Ae(s) {
+async function Fe(s) {
   const { layerInfo: e, config: i, category: t, errorStrings: a } = s, { layer: r } = e, { where: o } = i?.dataFilters ?? {}, { fetchNullValues: u } = i?.series?.[0]?.query ?? {}, d = u !== !0 ? `${t} IS NOT NULL` : "", g = {
     where: O([o, d]),
     // excluding the null values from the list
@@ -191,27 +190,27 @@ async function Ae(s) {
     }
   ), n;
 }
-function be(s) {
+function Ae(s) {
   return s !== void 0 && v(0, s)?.type === f.CategoryAxisFormat && v(1, s)?.type === f.CategoryAxisFormat;
 }
 export {
-  de as a,
-  ne as b,
-  Ae as c,
-  le as d,
-  ce as e,
-  ye as f,
-  re as g,
-  Fe as h,
-  be as i,
-  me as j,
-  pe as k,
-  oe as l,
+  ue as a,
+  oe as b,
+  Fe as c,
+  ne as d,
+  le as e,
+  xe as f,
+  ae as g,
+  pe as h,
+  Ae as i,
+  ye as j,
+  me as k,
+  re as l,
   v as m,
-  fe as n,
-  ge as o,
-  xe as p,
-  ue as r,
+  de as n,
+  fe as o,
+  ge as p,
+  ce as r,
   N as s,
-  ae as u
+  se as u
 };

package/dist/chunks/web-component-utils.js

@@ -7,11 +7,11 @@ import { g as me, a as de, b as ye } from "./pie-chart-data.js";
 import { g as ie } from "./series-length.js";
 import { g as re, d as le, e as ge } from "./serial-chart-data.js";
 import { g as _, a as pe } from "./data.js";
-import { Y as U, an as be, af as xe, aK as E, cm as Fe, B as V, a6 as De, bb as Se, d6 as Be } from "./index2.js";
+import { Y as U, ap as be, af as xe, aM as E, cM as Fe, B as V, a6 as De, bj as Se, dx as Be } from "./index2.js";
 import { k as H, az as $, g as R, as as ve, b as he, a as Q } from "./index.js";
 import { q as K, C as g, F as A } from "./index3.js";
 import { g as Pe } from "./series-types.js";
-import { V as Ve } from "./index6.js";
+import { V as Ve } from "./index5.js";
 import { DateTime as ne } from "luxon";
 import { P as X } from "./common.js";
 import { u as k, d as L } from "./chart-object-literals.js";

package/dist/chunks/x-bounds.js

@@ -5,8 +5,7 @@ import { G as g } from "./common.js";
 import { i as c } from "./rest-js-object-literals.js";
 import { u as x } from "./chart-object-literals.js";
 import { ai as S, M as L, T as b, a0 as T } from "./index.js";
-import { M as C } from "./index2.js";
-import { q as M, p as X } from "./index5.js";
+import { M as C, bF as M, bE as X } from "./index2.js";
 import { m as a, C as f } from "./model-setter.js";
 import { e as B, f as A } from "./utils2.js";
 import { l as p, s as y, h as O } from "./utils.js";
@@ -33,19 +32,19 @@ function d(t) {
 const V = (t) => {
   const { axis: e, index: i } = d(t);
   return e?.guides?.[i]?.visible ?? !0;
-}, R = (t) => {
+}, E = (t) => {
   const { visible: e, axis: i, index: s } = d(t);
   i?.guides?.[s] !== void 0 && (i.guides[s].visible = e);
 }, m = (t) => {
   const e = C(t.start, t.end);
   M(t.style) && e === c.SFS ? t.style = { type: c.SFS, color: t.style.color } : X(t.style) && e === c.SLS && (t.style = { type: c.SLS, color: t.style.color });
-}, E = (t) => {
+}, R = (t) => {
   const { axis: e, index: i } = d(t);
   return e?.guides?.[i]?.start ?? null;
-}, w = (t) => {
+}, F = (t) => {
   const { start: e, axis: i, index: s } = d(t);
   i?.guides?.[s] !== void 0 && (i.guides[s].start = e, m(i.guides[s]));
-}, F = (t) => {
+}, w = (t) => {
   const { axis: e, index: i } = d(t);
   return e?.guides?.[i]?.end;
 }, W = (t) => {
@@ -63,19 +62,19 @@ const V = (t) => {
 }, I = (t) => {
   const { labelText: e, axis: i, index: s } = d(t), o = i?.guides?.[s]?.label ?? S(e, L(b.GuideLabel), b.GuideLabel);
   i?.guides?.[s] !== void 0 && (i.guides[s].label = { ...o, text: e });
-}, q = (t) => {
+}, U = (t) => {
   const { axis: e, index: i } = d(t);
   return e?.guides?.[i]?.above ?? !1;
-}, U = (t) => {
+}, Y = (t) => {
   const { above: e, axis: i, index: s } = d(t);
   i?.guides?.[s] !== void 0 && (i.guides[s].above = e);
-}, Y = (t) => {
+}, q = (t) => {
   const { axis: e, index: i } = d(t);
   return e?.guides?.[i]?.style;
 }, z = (t) => {
   const { style: e, axis: i, index: s } = d(t);
   i?.guides?.[s] !== void 0 && (i.guides[s].style = e);
-}, Ge = (t) => {
+}, ve = (t) => {
   const { config: e, name: i, index: s, orientation: o } = t, n = o === g.X ? e.axes?.[0] : e.axes?.[1];
   if (n !== void 0) {
     n.guides = n.guides ?? [];
@@ -87,7 +86,7 @@ const V = (t) => {
     };
     s !== void 0 && s < n.guides.length ? n.guides.splice(s, 0, r) : n.guides.push(r);
   }
-}, _e = (t) => {
+}, Ge = (t) => {
   const { config: e, index: i, orientation: s } = t, o = s === g.X ? e.axes?.[0] : e.axes?.[1];
   o?.guides !== void 0 && (i !== void 0 && i < o.guides.length ? o.guides.splice(i, 1) : o.guides.pop());
 }, H = (t) => {
@@ -122,7 +121,7 @@ class l extends _ {
     return V({ config: this._config, index: e, orientation: i });
   }
   setGuideVisibility(e, i, s) {
-    R({ visible: e, config: this._config, index: i, orientation: s });
+    E({ visible: e, config: this._config, index: i, orientation: s });
   }
   /**
    * Gets the start value of a guide.
@@ -131,10 +130,10 @@ class l extends _ {
    * @param orientation - Default `y`. The axis orientation of the guide.
    */
   getGuideStart(e, i) {
-    return E({ config: this._config, index: e, orientation: i });
+    return R({ config: this._config, index: e, orientation: i });
   }
   setGuideStart(e, i, s) {
-    w({ start: e, config: this._config, index: i, orientation: s });
+    F({ start: e, config: this._config, index: i, orientation: s });
   }
   /**
    * Gets the end value of a guide.
@@ -143,7 +142,7 @@ class l extends _ {
    * @param orientation - Default `y`. The axis orientation of the guide.
    */
   getGuideEnd(e, i) {
-    return F({ config: this._config, index: e, orientation: i });
+    return w({ config: this._config, index: e, orientation: i });
   }
   setGuideEnd(e, i, s) {
     W({ end: e, config: this._config, index: i, orientation: s });
@@ -179,10 +178,10 @@ class l extends _ {
    * @param orientation - Default `y`. The axis orientation of the guide.
    */
   getGuideAbove(e, i) {
-    return q({ config: this._config, index: e, orientation: i });
+    return U({ config: this._config, index: e, orientation: i });
   }
   setGuideAbove(e, i, s) {
-    U({ above: e, config: this._config, index: i, orientation: s });
+    Y({ above: e, config: this._config, index: i, orientation: s });
   }
   /**
    * Gets the guide style.
@@ -191,7 +190,7 @@ class l extends _ {
    * @param orientation - Default `y`. The axis orientation of the guide.
    */
   getGuideStyle(e, i) {
-    return Y({ config: this._config, index: e, orientation: i });
+    return q({ config: this._config, index: e, orientation: i });
   }
   setGuideStyle(e, i, s) {
     z({ style: e, config: this._config, index: i, orientation: s });
@@ -236,7 +235,7 @@ u([
 u([
   a
 ], l.prototype, "setTooltipReverseColor");
-class he extends f {
+class _e extends f {
   /**
    * Whether the x-axis labels are visible.
    */
@@ -302,8 +301,8 @@ class ae extends f {
 O(ae, [v, G]);
 export {
   l as M,
-  he as W,
+  _e as W,
   ae as a,
-  Ge as b,
-  _e as d
+  ve as b,
+  Ge as d
 };

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

@@ -606,37 +606,60 @@ export abstract class ArcgisChart extends LitElement {
   /** @internal */
   protected _messages: Partial<{ chartNotFoundWarning: string; }> & T9nMeta<{ chartNotFoundWarning: string; }>;
   /**
-   * Specifies the user action behavior for the chart.
+   * Specifies how user interactions on the chart are handled.
    *
-   * - `monoSelection`: Select a single data point or series, new selection replaces the previous one.
-   * - `multiSelection`: Select multiple data points or series, new selection adds to the previous one.
-   * - `multiSelectionWithCtrlKey`: Select multiple data points or series while holding the Ctrl key (Cmd on Mac). When the key is held, each new selection is added; otherwise, the selection is replaced.
-   * - `none`: No action is performed on user interaction.
-   * - `zoom`: Zoom into a specific area of the chart.
+   * - `monoSelection`: Select one data point or series at a time. Each new selection replaces the previous selection.
+   * - `multiSelection`: Select multiple data points or series. Each new selection is added to the existing selection.
+   * - `multiSelectionWithCtrlKey`: Select multiple data points or series only while holding Ctrl (or Cmd on macOS). Without the key, selection behaves like `monoSelection`.
+   * - `zoom`: Zoom into an area of the chart.
+   * - `none`: Disable interaction-driven selection and zoom actions.
    *
    * **Note**: Not applicable to gauges.
    */
   accessor actionMode: ActionModes | undefined;
   /**
-   * Whether to allow the object id to be used as a statistic other than `Count`.
+   * When `true`, object ID can be used as a numeric field for aggregated charts (for example, `sum` of `objectId`).
    *
    * @default false
    */
   accessor allowUsingObjectIdStat: boolean;
   /**
-   * Enable animation on the chart.
+   * When `true`, elements such as series, axes, and legends will animate when the chart is first rendered or when the chart's configuration is updated.
+   *
+   * <video
+   *   src="https://developers.arcgis.com/javascript/latest/assets/references/components/chart/animationEnabled.webm"
+   *   aria-label="animationEnabled"
+   *   width="720"
+   *   autoPlay
+   *   loop
+   *   muted
+   *   playsInline
+   * />
    *
    * @default false
+   * @since 5.1
    */
   accessor animationEnabled: boolean | undefined;
   /**
-   * The ARIA attributes for the chart. Provides accessibility information to assistive technologies such as screen readers. Supports the following properties: [\`label\`](https://developer.mozilla.org/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label), [\`description\`](https://developer.mozilla.org/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-description), [\`describedByElements\`](https://developer.mozilla.org/docs/Web/API/Element/ariaDescribedByElements), and [\`labelledByElements\`](https://developer.mozilla.org/docs/Web/API/Element/ariaLabelledByElements).
+   * The ARIA attributes for the chart component. Provides accessibility information to assistive technologies such as screen readers. Supports the following properties: [\`label\`](https://developer.mozilla.org/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label), [\`description\`](https://developer.mozilla.org/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-description), [\`describedByElements\`](https://developer.mozilla.org/docs/Web/API/Element/ariaDescribedByElements), and [\`labelledByElements\`](https://developer.mozilla.org/docs/Web/API/Element/ariaLabelledByElements).
    *
+   * @example
+   * ```ts
+   * chartElement.aria = {
+   *  label: "Custom chart label",
+   *  description: "Custom chart description",
+   * };
+   * ```
+   * @see [ARIA attributes](https://developers.arcgis.com/javascript/latest/accessibility/#aria-attributes)
    * @since 5.0
    */
   accessor aria: DOMContainerAria | undefined;
   /**
-   * 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/charts-components/components/arcgis-chart/#destroy)  method when you are done to prevent memory leaks.
+   * When `true`, the component is not destroyed automatically when it is disconnected from the document, which is useful when moving or temporarily hiding it.
+   *
+   * > [!CAUTION]
+   * >
+   * > Call the [destroy()](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#destroy) method when you are done to prevent memory leaks.
    *
    * @default false
    * @since 5.0
@@ -650,16 +673,20 @@ export abstract class ArcgisChart extends LitElement {
    */
   accessor autoDisposeChart: boolean;
   /**
-   * When `true`, the data label text color is automatically adjusted for readability based on its background.
-   * If the label is dark and appears over a dark series area, the text color is switched to either the chart background color or white.
+   * When `true`, the data label text color is automatically adjusted for readability based on its background, switching to either the chart background color or white when contrast with the series area is too low.
+   *
+   * | With `autoInverseDataLabelTextColor` | Without `autoInverseDataLabelTextColor` |
+   * | -------- | -------- |
+   * | ![autoInverseDataLabelTextColor true](https://developers.arcgis.com/javascript/latest/assets/references/components/chart/autoInverseDataLabelTextColorTrue.avif) | ![autoInverseDataLabelTextColor false](https://developers.arcgis.com/javascript/latest/assets/references/components/chart/autoInverseDataLabelTextColorFalse.avif) |
    *
    * **Note**: Applicable to heat charts only.
    *
    * @default false
+   * @since 4.34
    */
   accessor autoInverseDataLabelTextColor: boolean;
   /**
-   * Allows picking the Calcite CSS variables to use when applying a Calcite theme.
+   * Specifies the Calcite CSS variables to use when applying a Calcite theme.
    *
    * By default the following variables are used:
    * - background: `--calcite-color-foreground-1`
@@ -668,9 +695,10 @@ export abstract class ArcgisChart extends LitElement {
    * - secondary line: `--calcite-color-text-3`
    * - spinner: `--calcite-color-brand-hover`
    *
-   * The charts colors are overridden by those associated to those CSS variables, but only if they have not been
-   * customized beforehand.
+   * The chart colors are overridden by those associated to those CSS variables, but only if they have not been customized beforehand.
    *
+   * @see [Charts theming with Calcite CSS variables](https://developers.arcgis.com/javascript/latest/charts/features-and-capabilities/styling-and-theming/#theming-with-css-variables)
+   * @see [Components theming with Calcite](https://developers.arcgis.com/javascript/latest/building-your-ui/#styling-and-theming-with-calcite)
    * @since 5.1
    */
   accessor calciteThemingCSSVariables: CalciteThemeCSSVariables;
@@ -705,19 +733,20 @@ export abstract class ArcgisChart extends LitElement {
   accessor chartWillRender: PreRenderCallback | undefined;
   /**
    * Whether to use features uniquely designed for a chart currently being configured by a user via the UI.
-   * When true, the slotted charts action bar will expose an Edit chart action, surfaces relevant error states,
-   * and can show a helpful in-container placeholder about the chart’s purpose.
+   * When `true` and if the [`charts action bar`](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-charts-action-bar/) is slotted in the chart component,
+   * the action bar will expose an "Edit chart" action, surface relevant error states, and show a helpful in-container placeholder about the chart’s purpose.
    *
    * @default false
+   * @since 5.1
    */
   accessor configurationEnabled: boolean;
   /**
-   * Sets the cursor range when `actionMode` is set to `zoom`, `multiSelection` or `multiSelectionWithCtrlKey`.
+   * Defines how the cursor selection rectangle is constrained when [actionMode](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#actionMode) is `zoom`, `multiSelection`, or `multiSelectionWithCtrlKey`.
    *
-   * - `multi-axes`: Allows to draw a free rectangle.
-   * - `x-axis`: Allows to draw a rectangle bound to the x-axis.
-   * - `y-axis`: Allows to draw a rectangle bound to the y-axis.
-   * - `undefined`: Defaults to the preset behavior according to the chart type and action mode.
+   * - `multi-axes`: Allows drawing a free rectangle across both axes.
+   * - `x-axis`: Constrains the rectangle to the x-axis direction.
+   * - `y-axis`: Constrains the rectangle to the y-axis direction.
+   * - `undefined`: Uses the default behavior for the current chart type and action mode.
    *
    * **Note**: Not applicable to gauges.
    */
@@ -725,7 +754,19 @@ export abstract class ArcgisChart extends LitElement {
   /**
    * Callback function used to format the data labels. If the returned string contains HTML tags they will be interpreted as such.
    *
-   * **Note**: Not applicable to gauges.
+   * @example
+   * ```ts
+   * chartElement.dataLabelFormatter = (value) => {
+   *   return `<b>${value}</b><br /><u>Custom label</u>`;
+   * };
+   * ```
+   * <img
+   *   src="https://developers.arcgis.com/javascript/latest/assets/references/components/chart/dataLabelFormatter.avif"
+   *   alt="dataLabelFormatter true"
+   *   style="max-width: 900px; width: 100%; height: auto;"
+   * />
+   *
+   * **Note**: Not applicable to gauges and radar charts.
    */
   accessor dataLabelFormatter: ChartOptions["dataLabelFormatter"] | undefined;
   /**