@juspay/svelte-ui-components 2.75.0 → 2.76.0

package/dist/BarChart/BarChart.svelte

@@ -1,4 +1,5 @@
 <script lang="ts">
+  import { onMount } from 'svelte';
   import type {
     BarChartProperties,
     BarChartRenderContext,
@@ -6,6 +7,7 @@
     BarFillGradient,
     BarFillPattern
   } from './properties';
+  import type { ChartHighlightAPI } from '../_chart/highlight';
   import ChartContainer from '../_chart/ChartContainer.svelte';
   import Axis from '../_chart/Axis.svelte';
   import ChartTooltip from '../_chart/ChartTooltip.svelte';
@@ -62,6 +64,12 @@
     tooltipSnippet,
     empty,
     renderOverlay,
+    onChartReady,
+    highlightedIndex = null,
+    normaliseToFirstPoint = false,
+    topN,
+    overflowLabel = 'Other',
+    hideBarGraphics = false,
     onbarclick,
     onbarhover,
     testId,
@@ -76,6 +84,24 @@
   let hovered = $state<{ si: number; pi: number } | null>(null);
   let mouseX = $state(0);
   let mouseY = $state(0);
+  /** Internal tracking for the imperative highlight API (onChartReady). */
+  let apiHighlightedIndex = $state<number | null>(null);
+
+  // ── onMount: emit ChartHighlightAPI via onChartReady ──────────
+
+  onMount(() => {
+    if (typeof onChartReady !== 'function') {
+      return;
+    }
+    const api: ChartHighlightAPI = {
+      highlight: (index) => {
+        apiHighlightedIndex = index;
+      },
+      getCategories: () => labels,
+      type: 'bar-chart'
+    };
+    onChartReady(api);
+  });
 
   // ── Layout ─────────────────────────────────────────────────────
 
@@ -84,13 +110,91 @@
   let dims = $derived(computeChartDimensions(chartWidth, chartHeight));
 
   let isMulti = $derived(Array.isArray(series) && series.length > 0);
-  let resolvedSeries = $derived(isMulti ? series! : [{ name: '', data: data ?? [] }]);
+
+  // ── Raw resolved series (before transformations) ──────────────
+
+  let rawSeries = $derived(isMulti ? series! : [{ name: '', data: data ?? [] }]);
+
+  // ── normaliseToFirstPoint transformation ──────────────────────
+
+  /**
+   * When normaliseToFirstPoint is true, each value is expressed as a
+   * percentage of the series' first data point's value (baseline = 100).
+   * Series whose first point is zero are left unchanged to avoid division
+   * by zero.
+   */
+  let normalisedSeries = $derived.by(() => {
+    if (!normaliseToFirstPoint) {
+      return rawSeries;
+    }
+    return rawSeries.map((s) => {
+      const baseline = s.data[0]?.value ?? 0;
+      if (baseline === 0) {
+        return s;
+      }
+      return {
+        ...s,
+        data: s.data.map((d) => ({
+          ...d,
+          value: (d.value / baseline) * 100
+        }))
+      };
+    });
+  });
+
+  // ── topN transformation ────────────────────────────────────────
+
+  /**
+   * Clips to the top N bars (by first-series value, descending) and aggregates
+   * the rest into a single overflow bar. Operates on each series in parallel so
+   * the same category ordering is preserved across series.
+   * Only applies in non-multi or single-series mode (groupMode-agnostic:
+   * works by reordering labels, not by touching multi-series stacking).
+   */
+  let resolvedSeries = $derived.by(() => {
+    if (topN == null || normalisedSeries.length === 0) {
+      return normalisedSeries;
+    }
+    const firstSeriesData = normalisedSeries[0]?.data ?? [];
+    if (firstSeriesData.length <= topN) {
+      return normalisedSeries;
+    }
+    // Sort indices by first-series value descending
+    const sortedIndices = firstSeriesData
+      .map((d, i) => ({ value: d.value, i }))
+      .sort((a, b) => b.value - a.value)
+      .map((item) => item.i);
+
+    const topIndices = new Set(sortedIndices.slice(0, topN));
+
+    return normalisedSeries.map((s) => {
+      const topData = s.data.filter((_, idx) => topIndices.has(idx));
+      const overflowValue = s.data
+        .filter((_, idx) => !topIndices.has(idx))
+        .reduce((sum, d) => sum + d.value, 0);
+      return {
+        ...s,
+        data: [...topData, { label: overflowLabel, value: overflowValue }]
+      };
+    });
+  });
 
   let labels = $derived.by(() => {
     const first = resolvedSeries[0]?.data ?? [];
     return first.map((d) => d.label);
   });
 
+  // ── Effective highlighted index: merge declarative + imperative ─
+
+  /**
+   * The declarative `highlightedIndex` prop takes precedence when explicitly
+   * set (non-null). The imperative API writes to `apiHighlightedIndex`.
+   * When both are null the chart renders normally (no dimming).
+   */
+  let effectiveHighlightedIndex = $derived(
+    highlightedIndex != null ? highlightedIndex : apiHighlightedIndex
+  );
+
   let isNormalized = $derived(stackNormalize && isMulti && groupMode === 'stacked');
 
   /** When stackNormalize is active and no custom valueFormat is supplied, append % so the
@@ -606,53 +710,61 @@
               </g>
             {/if}
 
-            {#each bars as bar, i (i)}
-              <!-- svelte-ignore a11y_no_static_element_interactions -->
-              <!-- svelte-ignore a11y_click_events_have_key_events -->
-              {#if isStackedMode && barRadius > 0}
-                <path
-                  class="bar"
-                  class:hovered={hovered?.si === bar.si && hovered?.pi === bar.pi}
-                  class:dimmed={hovered !== null &&
-                    (hovered.si !== bar.si || hovered.pi !== bar.pi)}
-                  d={stackedBarPath(bar)}
-                  fill={barFillAttr(bar)}
-                  aria-label="{bar.dataPoint.label}: {getDisplayValue(bar)}"
-                  onmouseenter={(e) => handleEnter(e, bar)}
-                  onmousemove={trackMouse}
-                  onmouseleave={handleLeave}
-                  onclick={() => handleClick(bar)}
-                />
-              {:else}
-                <rect
-                  class="bar"
-                  class:hovered={hovered?.si === bar.si && hovered?.pi === bar.pi}
-                  class:dimmed={hovered !== null &&
-                    (hovered.si !== bar.si || hovered.pi !== bar.pi)}
-                  x={bar.x}
-                  y={bar.y}
-                  width={bar.width}
-                  height={bar.height}
-                  rx={barRadius}
-                  ry={barRadius}
-                  fill={barFillAttr(bar)}
-                  aria-label="{bar.dataPoint.label}: {getDisplayValue(bar)}"
-                  onmouseenter={(e) => handleEnter(e, bar)}
-                  onmousemove={trackMouse}
-                  onmouseleave={handleLeave}
-                  onclick={() => handleClick(bar)}
-                />
-              {/if}
-              {#if showValues && !isStackedMode}
-                <text
-                  class="bar-value"
-                  x={isVertical ? bar.x + bar.width / 2 : bar.x + bar.width + 4}
-                  y={isVertical ? bar.y - 4 : bar.y + bar.height / 2}
-                  text-anchor={isVertical ? 'middle' : 'start'}
-                  dominant-baseline={isVertical ? 'auto' : 'middle'}>{getDisplayValue(bar)}</text
-                >
-              {/if}
-            {/each}
+            {#if !hideBarGraphics}
+              {#each bars as bar, i (i)}
+                <!-- svelte-ignore a11y_no_static_element_interactions -->
+                <!-- svelte-ignore a11y_click_events_have_key_events -->
+                {#if isStackedMode && barRadius > 0}
+                  <path
+                    class="bar"
+                    class:hovered={hovered?.si === bar.si && hovered?.pi === bar.pi}
+                    class:highlighted={effectiveHighlightedIndex !== null &&
+                      effectiveHighlightedIndex === bar.pi}
+                    class:dimmed={(hovered !== null &&
+                      (hovered.si !== bar.si || hovered.pi !== bar.pi)) ||
+                      (effectiveHighlightedIndex !== null && effectiveHighlightedIndex !== bar.pi)}
+                    d={stackedBarPath(bar)}
+                    fill={barFillAttr(bar)}
+                    aria-label="{bar.dataPoint.label}: {getDisplayValue(bar)}"
+                    onmouseenter={(e) => handleEnter(e, bar)}
+                    onmousemove={trackMouse}
+                    onmouseleave={handleLeave}
+                    onclick={() => handleClick(bar)}
+                  />
+                {:else}
+                  <rect
+                    class="bar"
+                    class:hovered={hovered?.si === bar.si && hovered?.pi === bar.pi}
+                    class:highlighted={effectiveHighlightedIndex !== null &&
+                      effectiveHighlightedIndex === bar.pi}
+                    class:dimmed={(hovered !== null &&
+                      (hovered.si !== bar.si || hovered.pi !== bar.pi)) ||
+                      (effectiveHighlightedIndex !== null && effectiveHighlightedIndex !== bar.pi)}
+                    x={bar.x}
+                    y={bar.y}
+                    width={bar.width}
+                    height={bar.height}
+                    rx={barRadius}
+                    ry={barRadius}
+                    fill={barFillAttr(bar)}
+                    aria-label="{bar.dataPoint.label}: {getDisplayValue(bar)}"
+                    onmouseenter={(e) => handleEnter(e, bar)}
+                    onmousemove={trackMouse}
+                    onmouseleave={handleLeave}
+                    onclick={() => handleClick(bar)}
+                  />
+                {/if}
+                {#if showValues && !isStackedMode}
+                  <text
+                    class="bar-value"
+                    x={isVertical ? bar.x + bar.width / 2 : bar.x + bar.width + 4}
+                    y={isVertical ? bar.y - 4 : bar.y + bar.height / 2}
+                    text-anchor={isVertical ? 'middle' : 'start'}
+                    dominant-baseline={isVertical ? 'auto' : 'middle'}>{getDisplayValue(bar)}</text
+                  >
+                {/if}
+              {/each}
+            {/if}
 
             <!-- A1-4: renderOverlay escape hatch — rendered after all bars -->
             {#if typeof renderOverlay === 'function'}
@@ -691,6 +803,9 @@
   .bar.hovered {
     opacity: var(--barchart-bar-hover-opacity, 1);
   }
+  .bar.highlighted {
+    opacity: var(--barchart-bar-highlighted-opacity, 1);
+  }
   .bar.dimmed {
     opacity: var(--barchart-bar-dimmed-opacity, 0.3);
   }

package/dist/BarChart/properties.d.ts

@@ -1,4 +1,5 @@
 import type { Snippet } from 'svelte';
+import type { ChartHighlightAPI } from '../_chart/highlight';
 export type BarFillPattern = {
     pattern: {
         /** SVG pattern element type: 'lines' | 'dots' | 'crosshatch' */
@@ -112,6 +113,46 @@ export type OptionalBarChartProperties = {
      * live in SVG coordinate space.
      */
     renderOverlay?: Snippet<[BarChartRenderContext]>;
+    /**
+     * Called once on mount with an imperative `ChartHighlightAPI` handle.
+     * Use `api.highlight(index)` to emphasise a specific bar (by its zero-based
+     * position within the category axis) and dim all others. Pass `null` to clear.
+     * The `type` field on the handle is always `'bar-chart'`.
+     */
+    onChartReady?: (api: ChartHighlightAPI) => void;
+    /**
+     * Declarative complement to `onChartReady`. When set to a non-null number the
+     * bar at that zero-based category index is highlighted (full opacity) and the
+     * remaining bars are dimmed. Set to `null` or omit to show all bars normally.
+     */
+    highlightedIndex?: number | null;
+    /**
+     * When `true`, each series' values are expressed as a percentage of that
+     * series' own first data point. A value equal to the baseline renders as 100,
+     * a value twice the baseline as 200, and so on. Useful for comparing relative
+     * growth across series that start at very different absolute levels.
+     * Has no effect on series that have no data or whose first point is zero.
+     */
+    normaliseToFirstPoint?: boolean;
+    /**
+     * When set, only the top `topN` bars (by descending value) are shown
+     * individually. The remaining bars are aggregated into a single bar whose
+     * value is the sum of all omitted bars and whose label is `overflowLabel`
+     * (default `"Other"`). Has no effect when the data has `topN` or fewer bars.
+     * In multi-series mode the ranking is based on the first series.
+     */
+    topN?: number;
+    /**
+     * Label for the aggregated overflow bar produced by `topN`. Defaults to
+     * `"Other"`. Has no effect when `topN` is not set.
+     */
+    overflowLabel?: string;
+    /**
+     * When `true`, bar rectangles are not rendered. Only the axis labels, gridlines,
+     * and legend remain visible. Useful for building legend-only or label-only
+     * thumbnails alongside a full chart.
+     */
+    hideBarGraphics?: boolean;
     testId?: string;
     classes?: string;
 };

package/dist/DeltaIndicator/DeltaIndicator.svelte

@@ -0,0 +1,87 @@
+<script lang="ts">
+  import type { DeltaIndicatorProperties, DeltaDirection } from './properties';
+
+  let {
+    value,
+    format,
+    invertColors = false,
+    hideArrow = false,
+    neutralThreshold = 0,
+    testId,
+    classes
+  }: DeltaIndicatorProperties = $props();
+
+  const defaultFormat = (input: number): string => `${Math.round(Math.abs(input))}%`;
+
+  // A negative threshold would invert the neutral band and misclassify direction, so
+  // clamp it to a non-negative value before the comparison math.
+  const safeNeutralThreshold = $derived(Math.max(0, neutralThreshold));
+
+  let direction = $derived<DeltaDirection>(
+    value > safeNeutralThreshold ? 'up' : value < -safeNeutralThreshold ? 'down' : 'neutral'
+  );
+
+  // Tone drives the color. 'up' reads as positive by default; invertColors flips
+  // the positive/negative tone for lower-is-better metrics. Neutral is always muted.
+  let tone = $derived(
+    direction === 'neutral'
+      ? 'neutral'
+      : (direction === 'up') !== invertColors
+        ? 'positive'
+        : 'negative'
+  );
+
+  let text = $derived((format ?? defaultFormat)(value));
+</script>
+
+<span
+  class="delta-indicator delta-{tone} {classes ?? ''}"
+  data-pw={typeof testId === 'string' ? testId : null}
+>
+  {#if !hideArrow && direction !== 'neutral'}
+    <span class="delta-indicator-arrow delta-arrow-{direction}" aria-hidden="true">
+      <svg viewBox="0 0 10 10"><path d="M5 1 L9 8 L1 8 Z" /></svg>
+    </span>
+  {/if}
+  <span class="delta-indicator-text">{text}</span>
+</span>
+
+<style>
+  .delta-indicator {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--delta-indicator-gap, 2px);
+    font-size: var(--delta-indicator-font-size, 13px);
+    font-weight: var(--delta-indicator-font-weight, 600);
+    line-height: 1;
+  }
+
+  .delta-positive {
+    color: var(--delta-indicator-positive-color, #1a9d6f);
+  }
+
+  .delta-negative {
+    color: var(--delta-indicator-negative-color, #e5484d);
+  }
+
+  .delta-neutral {
+    color: var(--delta-indicator-neutral-color, #8a8a8a);
+  }
+
+  .delta-indicator-arrow {
+    display: inline-flex;
+    width: var(--delta-indicator-arrow-size, 9px);
+    height: var(--delta-indicator-arrow-size, 9px);
+    flex-shrink: 0;
+  }
+
+  .delta-indicator-arrow svg {
+    width: 100%;
+    height: 100%;
+    fill: currentColor;
+  }
+
+  .delta-arrow-down {
+    transform: rotate(180deg);
+  }
+</style>

package/dist/DeltaIndicator/DeltaIndicator.svelte.d.ts

@@ -0,0 +1,4 @@
+import type { DeltaIndicatorProperties } from './properties';
+declare const DeltaIndicator: import("svelte").Component<DeltaIndicatorProperties, {}, "">;
+type DeltaIndicator = ReturnType<typeof DeltaIndicator>;
+export default DeltaIndicator;

package/dist/DeltaIndicator/properties.d.ts

@@ -0,0 +1,26 @@
+export type DeltaIndicatorProperties = MandatoryDeltaIndicatorProperties & OptionalDeltaIndicatorProperties;
+export type DeltaDirection = 'up' | 'down' | 'neutral';
+export type MandatoryDeltaIndicatorProperties = {
+    /** The change amount; its sign selects the up / down / neutral direction. */
+    value: number;
+};
+export type OptionalDeltaIndicatorProperties = {
+    /**
+     * Formats the displayed text from the raw value. Default renders the rounded
+     * absolute value followed by a percent sign (e.g. `12%`).
+     */
+    format?: (value: number) => string;
+    /**
+     * Swap the up/down colors for lower-is-better metrics (e.g. bounce rate, RTO),
+     * where a decrease is "good" (positive tone) and an increase is "bad".
+     */
+    invertColors?: boolean;
+    /** Hide the directional arrow, showing only the formatted text. */
+    hideArrow?: boolean;
+    /** Absolute values at or below this are treated as `neutral` (default 0). */
+    neutralThreshold?: number;
+    /** Test selector applied as the `data-pw` attribute. */
+    testId?: string;
+    /** Additional CSS classes for theming. */
+    classes?: string;
+};

package/dist/DeltaIndicator/properties.js

@@ -0,0 +1 @@
+export {};