@juspay/svelte-ui-components 4.20.0 → 4.22.0

package/dist/AreaChart/AreaChart.svelte

@@ -13,6 +13,7 @@
   import { measureText } from '../_chart/measure';
   import { resolvePointLabels } from '../_chart/labels';
   import { pointerPositionIn, dismissOnOutsidePointerDown } from '../_chart/interactions';
+  import { formatSeriesAggregate } from '../_chart/aggregate';
   import type { LegendItem, Point } from '../_chart/types';
   import { DEFAULT_CHART_MAX_HEIGHT } from '../_chart/types';
 
@@ -171,7 +172,15 @@
   });
 
   let legendItems = $derived<LegendItem[]>(
-    series.map((s, i) => ({ label: s.name, color: s.color ?? getColor(i) }))
+    series.map((s, i) => ({
+      label: s.name,
+      color: s.color ?? getColor(i),
+      aggregateLabel: formatSeriesAggregate(
+        s.data.map((d) => d.y),
+        s.aggregate ?? 'none',
+        s.aggregateFormat ?? yTickFormat ?? formatNumber
+      )
+    }))
   );
 
   // ── Tooltip ────────────────────────────────────────────────────

package/dist/AreaChart/properties.d.ts

@@ -1,5 +1,6 @@
 import type { Snippet } from 'svelte';
 import type { CurveType } from '../_chart/types';
+import type { SeriesAggregate } from '../_chart/aggregate';
 export type AreaChartDataPoint = {
     x: number;
     y: number;
@@ -9,6 +10,20 @@ export type AreaChartSeries = {
     name: string;
     data: AreaChartDataPoint[];
     color?: string;
+    /**
+     * Shows an aggregate of this series' `y` values beside its legend label
+     * (e.g. "Revenue  $128K"). Aggregates that series' own values only -- when
+     * `stacked` is true this is never the per-category stack total, which is a
+     * separate, existing computation. Omit (or `'none'`, the default) to show
+     * no aggregate; every chart renders unchanged without it.
+     */
+    aggregate?: SeriesAggregate;
+    /**
+     * Formatter for this series' legend aggregate. Defaults to the chart's own
+     * `yTickFormat` (or the built-in number formatter) -- set this only when
+     * the aggregate needs a different unit than the axis.
+     */
+    aggregateFormat?: (value: number) => string;
 };
 export type AreaChartTooltipContext = {
     x: number;

package/dist/BarChart/BarChart.svelte

@@ -29,6 +29,7 @@
     placedLabelRect,
     dropOverlapping
   } from '../_chart/labels';
+  import { formatSeriesAggregate } from '../_chart/aggregate';
   import type { LegendItem, BarRect } from '../_chart/types';
   import { DEFAULT_CHART_CORNER_RADIUS, DEFAULT_CHART_MAX_HEIGHT } from '../_chart/types';
   import type { TooltipAnchor } from '../_chart/types';
@@ -583,10 +584,22 @@
 
   let legendItems = $derived<LegendItem[]>(
     isMulti
-      ? resolvedSeries.map((s, i) => ({
+      ? rawSeries.map((s, i) => ({
           label: s.name,
           color: fallbackColor(s.color ?? getColor(i), i),
-          hidden: hiddenSeries.has(i)
+          hidden: hiddenSeries.has(i),
+          // Aggregates this series' own raw `value`s, from `rawSeries` rather
+          // than `resolvedSeries`: the latter may hold normaliseToFirstPoint
+          // percentages or topN-clipped/overflow values, neither of which is
+          // the series' real data (never the cross-series stack total either,
+          // which is an unrelated existing computation). Defaults to the
+          // chart's own `valueFormat`/number formatter, matching the "reuse
+          // the axis/tooltip formatting mechanism" rule.
+          aggregateLabel: formatSeriesAggregate(
+            s.data.map((d) => d.value),
+            s.aggregate ?? 'none',
+            s.aggregateFormat ?? format
+          )
         }))
       : []
   );

package/dist/BarChart/properties.d.ts

@@ -1,5 +1,6 @@
 import type { Snippet } from 'svelte';
 import type { ChartHighlightAPI } from '../_chart/highlight';
+import type { SeriesAggregate } from '../_chart/aggregate';
 export type BarFillPattern = {
     pattern: {
         /** SVG pattern element type: 'lines' | 'dots' | 'crosshatch' */
@@ -52,6 +53,21 @@ export type BarChartSeries = {
     data: BarChartDataPoint[];
     /** Series-level fill: plain color, pattern, or gradient. */
     color?: BarFill;
+    /**
+     * Shows an aggregate of this series' `value`s beside its legend label (e.g.
+     * "Revenue  $128K"). Aggregates that series' own values only -- in
+     * `groupMode="stacked"` this is never the per-category stack total, which
+     * is a separate, existing computation. Omit (or `'none'`, the default) to
+     * show no aggregate; every chart renders unchanged without it.
+     */
+    aggregate?: SeriesAggregate;
+    /**
+     * Formatter for this series' legend aggregate. Defaults to the chart's own
+     * `valueFormat` (or the built-in number formatter) -- set this only when
+     * the aggregate needs a different unit than the axis, e.g. a percentage
+     * average alongside a currency-formatted axis.
+     */
+    aggregateFormat?: (value: number) => string;
 };
 /**
  * Geometry for a single rendered bar, in inner (post-margin) coordinates — the

package/dist/ChatMessage/ChatMessage.svelte

@@ -570,6 +570,11 @@
     opacity: var(--chat-message-blockquote-opacity, 0.85);
   }
 
+  /* Fallback for a bare <table> in caller-supplied `html`, which has no scroll
+     container of its own: it keeps the block treatment so a wide table scrolls
+     rather than overflowing the message. A table that came from `markdown` (or
+     from `renderMarkdown`) arrives inside `.markdown-table-wrapper`, and the
+     rules below take it back out of block layout. */
   .body :global(table) {
     display: block;
     max-width: 100%;
@@ -578,6 +583,40 @@
     margin: 0.5em 0;
   }
 
+  /* The wrapper scrolls, not the table. `display: block` on a <table> is what
+     makes `overflow-x` work on the element itself, but it strips the table's
+     semantics for assistive technology -- a screen reader loses row and column
+     navigation. MarkdownText separates the scroll container from the table for
+     exactly that reason; this component rendered the same wrapper markup and
+     styled the table instead, so a chat table was scrollable and no longer a
+     table. Chat is where markdown tables overwhelmingly land. */
+  .body :global(.markdown-table-wrapper) {
+    display: block;
+    max-width: 100%;
+    overflow-x: auto;
+    margin: 0.5em 0;
+  }
+
+  /* The wrapper is a tab stop (the renderer emits tabindex="0" so the scroll is
+     reachable by keyboard). The browser's default ring already applies; this
+     replaces it with the same 2px treatment the rest of the library uses, since
+     the 1px UA default is easy to miss against a message bubble. */
+  .body :global(.markdown-table-wrapper:focus-visible) {
+    outline: 2px solid var(--chat-message-table-focus-outline-color, #3b82f6);
+    outline-offset: 2px;
+  }
+
+  /* Without an intrinsic width the table is exactly its container's width and a
+     wide table compresses instead of scrolling. `max-content` supplies it;
+     `min-width` keeps a narrow table filling the bubble. */
+  .body :global(.markdown-table-wrapper table) {
+    display: table;
+    width: max-content;
+    min-width: 100%;
+    overflow-x: visible;
+    margin: 0;
+  }
+
   .body :global(th),
   .body :global(td) {
     padding: 5px 10px;

package/dist/DualAxisBarChart/DualAxisBarChart.svelte

@@ -18,6 +18,7 @@
   import { getColor } from '../_chart/colors';
   import { formatNumber } from '../_chart/format';
   import { roundedRectPath, linePath } from '../_chart/paths';
+  import { formatSeriesAggregate } from '../_chart/aggregate';
   import type {
     LegendItem,
     TooltipData,
@@ -280,7 +281,17 @@
     series.map((s, si) => ({
       label: s.name,
       color: resolvedColor(s, si),
-      hidden: hiddenSeries.has(si)
+      hidden: hiddenSeries.has(si),
+      // Defaults to the same per-axis formatter (leftFormat/rightFormat, used
+      // for ticks/tooltip above) as whichever axis this series is plotted
+      // against, so a left-axis currency series and a right-axis percentage
+      // series each get a sensible default without either specifying
+      // `aggregateFormat`.
+      aggregateLabel: formatSeriesAggregate(
+        s.data,
+        s.aggregate ?? 'none',
+        s.aggregateFormat ?? (s.yAxisIndex === 0 ? leftFormat : rightFormat)
+      )
     }))
   );
 

package/dist/DualAxisBarChart/properties.d.ts

@@ -1,4 +1,5 @@
 import type { Snippet } from 'svelte';
+import type { SeriesAggregate } from '../_chart/aggregate';
 /**
  * Configuration for one of the two independent Y-axes.
  */
@@ -37,6 +38,20 @@ export type DualAxisSeries = {
      * `'line'`   — line with optional dots drawn over the column layer.
      */
     type?: 'column' | 'line';
+    /**
+     * Shows an aggregate of this series' values beside its legend label (e.g.
+     * "Revenue  $128K"). Omit (or `'none'`, the default) to show no aggregate;
+     * every chart renders unchanged without it.
+     */
+    aggregate?: SeriesAggregate;
+    /**
+     * Formatter for this series' legend aggregate. Defaults to the `valueFormat`
+     * of whichever axis (`leftAxis`/`rightAxis`) this series' `yAxisIndex`
+     * points at -- reusing the same per-axis formatting the chart already has,
+     * rather than a parallel mechanism. Set this only when the aggregate needs
+     * a different unit than its axis.
+     */
+    aggregateFormat?: (value: number) => string;
 };
 /**
  * Data passed to `tooltipSnippet` when the user hovers a category.

package/dist/LineChart/LineChart.svelte

@@ -14,6 +14,7 @@
   import { formatNumber, defaultTickFormat } from '../_chart/format';
   import { measureText } from '../_chart/measure';
   import { resolvePointLabels } from '../_chart/labels';
+  import { formatSeriesAggregate } from '../_chart/aggregate';
   import type { LegendItem, Point, TooltipAnchor } from '../_chart/types';
   import { pointerPositionIn, dismissOnOutsidePointerDown } from '../_chart/interactions';
   import { SvelteSet } from 'svelte/reactivity';
@@ -236,7 +237,12 @@
     series.map((s, i) => ({
       label: s.name,
       color: s.color ?? getColor(i),
-      hidden: hiddenSeries.has(i)
+      hidden: hiddenSeries.has(i),
+      aggregateLabel: formatSeriesAggregate(
+        s.data.map((d) => d.y),
+        s.aggregate ?? 'none',
+        s.aggregateFormat ?? yTickFormat ?? formatNumber
+      )
     }))
   );
 

package/dist/LineChart/properties.d.ts

@@ -1,6 +1,7 @@
 import type { Snippet } from 'svelte';
 import type { CurveType } from '../_chart/types';
 import type { ChartHighlightAPI } from '../_chart/highlight';
+import type { SeriesAggregate } from '../_chart/aggregate';
 export type LineChartDataPoint = {
     x: number;
     y: number;
@@ -16,6 +17,19 @@ export type LineChartSeries = {
      * custom SVG `stroke-dasharray`. Omit for a solid line.
      */
     dash?: boolean | string;
+    /**
+     * Shows an aggregate of this series' `y` values beside its legend label
+     * (e.g. "Revenue  $128K"). Omit (or `'none'`, the default) to show no
+     * aggregate; every chart renders unchanged without it.
+     */
+    aggregate?: SeriesAggregate;
+    /**
+     * Formatter for this series' legend aggregate. Defaults to the chart's own
+     * `yTickFormat` (or the built-in number formatter) -- set this only when
+     * the aggregate needs a different unit than the axis, e.g. a percentage
+     * average alongside a count-formatted axis.
+     */
+    aggregateFormat?: (value: number) => string;
 };
 export type LineChartTooltipContext = {
     x: number;

package/dist/MarkdownText/MarkdownText.svelte

@@ -8,10 +8,13 @@
     testId,
     classes,
     tableLabel,
+    tableWrapperClass,
     sanitize
   }: MarkdownTextProperties = $props();
 
-  let html = $derived(renderMarkdown(markdown, { breaks, tableLabel, sanitize }));
+  let html = $derived(
+    renderMarkdown(markdown, { breaks, tableLabel, tableWrapperClass, sanitize })
+  );
 </script>
 
 <div

package/dist/MarkdownText/markdown.js

@@ -245,14 +245,32 @@ function annotateExternalLinks(html) {
    scrollable region with a tabindex. */
 const TABLE_OPEN = /<table>/g;
 const TABLE_CLOSE = /<\/table>/g;
-function wrapTables(html, label) {
+const DEFAULT_TABLE_WRAPPER_CLASS = 'markdown-table-wrapper';
+function wrapTables(html, label, wrapperClass) {
     /* `role="region"` without an accessible name announces a landmark the user
        cannot identify, which is worse than no landmark, so the role appears only
        when the caller supplies a name. The tabindex does not depend on it:
        keyboard scrolling should work either way. */
+    /* A caller's class is ADDED, never substituted. The wrapper's own styling --
+       `overflow-x: auto`, the `:focus-visible` ring, and the table's max-content
+       width -- is scoped to `.markdown-table-wrapper` in MarkdownText.svelte, and
+       a Svelte scoped selector cannot be templated to a name supplied at runtime.
+       Substituting the class would leave a `tabindex="0"` element that cannot
+       scroll and shows no focus ring, undoing the fix that made a wide table
+       keyboard-scrollable in the first place. Adding costs a consumer nothing:
+       their own selector still matches, and they can still override by
+       specificity. */
+    const custom = typeof wrapperClass === 'string' ? wrapperClass.trim() : '';
+    // The caller's value lands inside a double-quoted HTML attribute, same as
+    // `label` below -- escaping it the same way is what stops a value like
+    // `" onmouseover="alert(1)` from closing the attribute early and injecting a
+    // new one. The built-in name is a literal and needs no escaping.
+    const classAttr = custom.length > 0
+        ? `${DEFAULT_TABLE_WRAPPER_CLASS} ${escapeHtml(custom)}`
+        : DEFAULT_TABLE_WRAPPER_CLASS;
     const open = typeof label === 'string' && label.length > 0
-        ? `<div class="markdown-table-wrapper" tabindex="0" role="region" aria-label="${escapeHtml(label)}">`
-        : '<div class="markdown-table-wrapper" tabindex="0">';
+        ? `<div class="${classAttr}" tabindex="0" role="region" aria-label="${escapeHtml(label)}">`
+        : `<div class="${classAttr}" tabindex="0">`;
     return html.replace(TABLE_OPEN, `${open}<table>`).replace(TABLE_CLOSE, '</table></div>');
 }
 function instanceFor(options) {
@@ -292,5 +310,7 @@ export function renderMarkdown(markdown, options = {}) {
     }
     /* Inline parsing produces no block elements, so there is no table to wrap. */
     const linked = annotateExternalLinks(output);
-    return options.inline === true ? linked : wrapTables(linked, options.tableLabel);
+    return options.inline === true
+        ? linked
+        : wrapTables(linked, options.tableLabel, options.tableWrapperClass);
 }

package/dist/MarkdownText/properties.d.ts

@@ -20,6 +20,15 @@ export type OptionalMarkdownTextProperties = {
      * worse than none.
      */
     tableLabel?: string;
+    /**
+     * Extra class name added to the scrollable region wrapping each table,
+     * alongside the built-in `markdown-table-wrapper` rather than replacing it
+     * (the wrapper's scroll/focus behaviour is scoped to that class and cannot
+     * be retargeted). Lets a consumer whose own stylesheet targets a different
+     * class keep that styling too. Omitting it, or passing an empty or
+     * whitespace-only string, keeps only `markdown-table-wrapper`.
+     */
+    tableWrapperClass?: string;
     /**
      * Narrow which URL protocols survive on rendered links/images. See
      * `MarkdownSanitizeOptions`.
@@ -104,6 +113,8 @@ export type RenderMarkdownOptions = {
     inline?: boolean;
     /** Accessible name for the scroll region wrapping each table. See `MarkdownTextProperties.tableLabel`. */
     tableLabel?: string;
+    /** Class name for the scroll region wrapping each table. See `MarkdownTextProperties.tableWrapperClass`. */
+    tableWrapperClass?: string;
     /** Narrow the protocol allow-list. See `MarkdownSanitizeOptions`. */
     sanitize?: MarkdownSanitizeOptions;
 };

package/dist/Table/Table.svelte

@@ -51,7 +51,8 @@
     summaryRowIndex = null,
     headerTooltipIcon,
     headerTooltipPosition,
-    usePortal = false
+    usePortal = false,
+    labels
   }: TableProperties = $props();
 
   // ─── Keyed column model → positional projection ─────────────────────────────
@@ -646,7 +647,7 @@
         class="table-search-clear"
         type="button"
         onclick={clearSearch}
-        aria-label="Clear search"
+        aria-label={labels?.clearSearch ?? 'Clear search'}
       >
         <!-- eslint-disable svelte/no-at-html-tags -->
         {@html closeSvg}
@@ -688,7 +689,7 @@
                        so the tri-state is computed here and never flipped locally. -->
                   <Checkbox
                     text=""
-                    ariaLabel="Select all rows"
+                    ariaLabel={labels?.selectAllRows ?? 'Select all rows'}
                     controlled
                     checked={headerCheckboxState === 'all'}
                     indeterminate={headerCheckboxState === 'some'}
@@ -773,7 +774,7 @@
                             >
                               <Button
                                 {...triggerProps}
-                                ariaLabel="Filter by {header}"
+                                ariaLabel={labels?.filterBy?.(header) ?? `Filter by ${header}`}
                                 testId={headerColumn.testId &&
                                   `${headerColumn.testId}-filter-trigger`}
                               >
@@ -791,7 +792,10 @@
                     {/if}
                     {#if isColumnSortable(colIndex)}
                       <div class="sort-button">
-                        <Button onclick={() => handleSort(colIndex)} ariaLabel="Sort by {header}">
+                        <Button
+                          onclick={() => handleSort(colIndex)}
+                          ariaLabel={labels?.sortBy?.(header) ?? `Sort by ${header}`}
+                        >
                           {#if sortColumn === colIndex && sortDirection === 'asc'}
                             {#if typeof sortAscIcon === 'function'}
                               {@render sortAscIcon()}
@@ -840,7 +844,7 @@
                             <Button
                               variant="ghost"
                               iconOnly={true}
-                              ariaLabel="Close search"
+                              ariaLabel={labels?.closeSearch ?? 'Close search'}
                               onclick={clearSearch}
                             >
                               {#snippet icon()}
@@ -921,7 +925,8 @@
                     >
                       <Checkbox
                         text=""
-                        ariaLabel={`Select row ${rowId || 'non-selectable'}`}
+                        ariaLabel={labels?.selectRow?.(rowId) ??
+                          `Select row ${rowId || 'non-selectable'}`}
                         controlled
                         checked={rowSelected}
                         disabled={rowDisabled}

package/dist/Table/properties.d.ts

@@ -434,7 +434,39 @@ export type TableSearchConfig = {
     displayMode?: 'toolbar' | 'inline';
 };
 export type TableProperties = OptionalTableProperties & TableEventProperties;
+/**
+ * Accessible names Table generates for its own controls, for callers who do
+ * not ship an English UI.
+ *
+ * Every member is optional and falls back to the English string Table has
+ * always used, so adding this prop changes nothing for existing consumers.
+ *
+ * The two that depend on a column, and the one that depends on a row, are
+ * functions rather than templates with a placeholder: a translator needs to
+ * put the header where their grammar wants it, not where an English sentence
+ * happens to leave a slot.
+ *
+ * `Search` is deliberately absent -- `searchConfig.placeholder` already names
+ * the search input and has since search shipped.
+ */
+export type TableLabels = {
+    /** Sort button on a column header. Default: `Sort by ${header}`. */
+    sortBy?: (header: string) => string;
+    /** Filter trigger on a column header. Default: `Filter by ${header}`. */
+    filterBy?: (header: string) => string;
+    /** Per-row selection checkbox. Receives the row id, or `''` when the row
+     *  cannot be selected -- the default spells that case out rather than
+     *  naming an empty row. Default: `Select row ${rowId || 'non-selectable'}`. */
+    selectRow?: (rowId: string) => string;
+    /** Header checkbox that selects every row on the page. Default: `Select all rows`. */
+    selectAllRows?: string;
+    /** Button that empties the search box. Default: `Clear search`. */
+    clearSearch?: string;
+    /** Button that dismisses the search box. Default: `Close search`. */
+    closeSearch?: string;
+};
 export type OptionalTableProperties = {
+    labels?: TableLabels;
     tableTitle?: string | null;
     tableHeaders?: string[];
     tableData?: Array<JSONValue[]>;

package/dist/_chart/Legend.svelte

@@ -11,22 +11,38 @@
     {:else}
       {#each items as item, i (i)}
         {#if typeof onToggle === 'function'}
-          <button
-            type="button"
-            class="legend-item legend-toggle"
-            class:legend-hidden={item.hidden}
-            aria-pressed={!item.hidden}
-            onclick={() => onToggle(i)}
-            data-pw={`legend-toggle-${i}`}
-            testID={`legend-toggle-${i}`}
-          >
-            <span class="legend-swatch" style="background: {item.color}"></span>
-            <span class="legend-label">{item.label}</span>
-          </button>
+          <!-- The aggregate sits OUTSIDE the button deliberately. Every bit of
+               text inside a button becomes part of its accessible name, so an
+               aggregate inside it would make the control's name change whenever
+               the data does -- "Revenue $6,500" today, something else tomorrow.
+               A name that moves breaks voice-control targeting and any consumer
+               test matching it exactly, and announces a figure as the control's
+               identity rather than as information about the series. It also
+               stops a number being a click target for toggling a series, which
+               it never should have been. -->
+          <div class="legend-item" class:legend-hidden={item.hidden}>
+            <button
+              type="button"
+              class="legend-toggle"
+              aria-pressed={!item.hidden}
+              onclick={() => onToggle(i)}
+              data-pw={`legend-toggle-${i}`}
+              testID={`legend-toggle-${i}`}
+            >
+              <span class="legend-swatch" style="background: {item.color}"></span>
+              <span class="legend-label">{item.label}</span>
+            </button>
+            {#if item.aggregateLabel}
+              <span class="legend-aggregate">{item.aggregateLabel}</span>
+            {/if}
+          </div>
         {:else}
           <div class="legend-item">
             <span class="legend-swatch" style="background: {item.color}"></span>
             <span class="legend-label">{item.label}</span>
+            {#if item.aggregateLabel}
+              <span class="legend-aggregate">{item.aggregateLabel}</span>
+            {/if}
           </div>
         {/if}
       {/each}
@@ -72,7 +88,18 @@
     color: var(--chart-legend-color, light-dark(#333, #e5e7eb));
   }
 
+  .legend-aggregate {
+    font-size: var(--chart-legend-font-size, 12px);
+    font-weight: 600;
+    color: var(--chart-legend-aggregate-color, light-dark(#111, #f5f5f5));
+  }
+
   .legend-toggle {
+    /* The button no longer IS the row -- it holds the swatch and label, and the
+       aggregate is its sibling -- so it carries its own flex layout. */
+    display: flex;
+    align-items: center;
+    gap: 6px;
     background: none;
     border: none;
     padding: 0;
@@ -85,7 +112,8 @@
     opacity: 0.25;
   }
 
-  .legend-hidden .legend-label {
+  .legend-hidden .legend-label,
+  .legend-hidden .legend-aggregate {
     color: var(--chart-legend-hidden-color, light-dark(#bbb, #555));
   }
 </style>

package/dist/_chart/aggregate.d.ts

@@ -0,0 +1,35 @@
+/**
+ * How a chart legend summarises a series' values into one number shown
+ * beside its label. `'none'` (the default for every series that doesn't set
+ * this) shows nothing -- the feature is purely additive.
+ */
+export type SeriesAggregate = 'sum' | 'average' | 'min' | 'max' | 'none';
+/**
+ * Reduces a series' values to a single number for its legend entry.
+ *
+ * Null and non-finite entries (a missing point, or `NaN`/`Infinity` slipping
+ * through past the `number` type at runtime) are treated as ABSENT rather
+ * than as zero -- they are skipped entirely, not summed/counted as 0. This
+ * only changes the result for `average` (skipping shrinks the denominator)
+ * and `min`/`max` (an absent point can never set an extreme); `sum` is
+ * identical either way since 0 is the additive identity.
+ *
+ * Zero remaining values after skipping -- an empty series, or one whose
+ * points are all absent -- resolves to `null` for EVERY kind, `sum`
+ * included: a "total" of 0 for a series with no real data would be a
+ * fabricated number, not an observed one, so the legend renders nothing
+ * rather than a misleading 0.
+ *
+ * Aggregation is always over one series' own values, never across a stack --
+ * a stacked bar/area chart's per-category stack total is an unrelated,
+ * existing computation (the y-domain sum) that this function does not touch.
+ */
+export declare function computeSeriesAggregate(values: ReadonlyArray<number | null>, aggregate: SeriesAggregate): number | null;
+/**
+ * Computes and formats a series aggregate for legend display in one step,
+ * reusing the chart's own value formatter (the same one driving its
+ * axis/tooltip) rather than a parallel formatting path. Returns `null` --
+ * render nothing -- whenever there is no aggregate to show, so the formatter
+ * is never handed `NaN` and a caller never needs its own null guard.
+ */
+export declare function formatSeriesAggregate(values: ReadonlyArray<number | null>, aggregate: SeriesAggregate, format: (value: number) => string): string | null;

package/dist/_chart/aggregate.js

@@ -0,0 +1,68 @@
+/**
+ * Reduces a series' values to a single number for its legend entry.
+ *
+ * Null and non-finite entries (a missing point, or `NaN`/`Infinity` slipping
+ * through past the `number` type at runtime) are treated as ABSENT rather
+ * than as zero -- they are skipped entirely, not summed/counted as 0. This
+ * only changes the result for `average` (skipping shrinks the denominator)
+ * and `min`/`max` (an absent point can never set an extreme); `sum` is
+ * identical either way since 0 is the additive identity.
+ *
+ * Zero remaining values after skipping -- an empty series, or one whose
+ * points are all absent -- resolves to `null` for EVERY kind, `sum`
+ * included: a "total" of 0 for a series with no real data would be a
+ * fabricated number, not an observed one, so the legend renders nothing
+ * rather than a misleading 0.
+ *
+ * Aggregation is always over one series' own values, never across a stack --
+ * a stacked bar/area chart's per-category stack total is an unrelated,
+ * existing computation (the y-domain sum) that this function does not touch.
+ */
+export function computeSeriesAggregate(values, aggregate) {
+    if (aggregate === 'none') {
+        return null;
+    }
+    let sum = 0;
+    let count = 0;
+    let min = Infinity;
+    let max = -Infinity;
+    for (const value of values) {
+        if (value === null || !Number.isFinite(value)) {
+            continue;
+        }
+        sum += value;
+        count += 1;
+        if (value < min) {
+            min = value;
+        }
+        if (value > max) {
+            max = value;
+        }
+    }
+    if (count === 0) {
+        return null;
+    }
+    switch (aggregate) {
+        case 'sum':
+            return sum;
+        case 'average':
+            return sum / count;
+        case 'min':
+            return min;
+        case 'max':
+            return max;
+        default:
+            return null;
+    }
+}
+/**
+ * Computes and formats a series aggregate for legend display in one step,
+ * reusing the chart's own value formatter (the same one driving its
+ * axis/tooltip) rather than a parallel formatting path. Returns `null` --
+ * render nothing -- whenever there is no aggregate to show, so the formatter
+ * is never handed `NaN` and a caller never needs its own null guard.
+ */
+export function formatSeriesAggregate(values, aggregate, format) {
+    const value = computeSeriesAggregate(values, aggregate);
+    return value === null ? null : format(value);
+}