@juspay/svelte-ui-components 2.57.0 → 2.59.0

package/dist/BarChart/BarChart.svelte

@@ -1,5 +1,11 @@
 <script lang="ts">
-  import type { BarChartProperties } from './properties';
+  import type {
+    BarChartProperties,
+    BarChartRenderContext,
+    BarFill,
+    BarFillGradient,
+    BarFillPattern
+  } from './properties';
   import ChartContainer from '../_chart/ChartContainer.svelte';
   import Axis from '../_chart/Axis.svelte';
   import ChartTooltip from '../_chart/ChartTooltip.svelte';
@@ -8,7 +14,28 @@
   import { computeChartDimensions } from '../_chart/geometry';
   import { getColor } from '../_chart/colors';
   import { formatNumber } from '../_chart/format';
+  import { roundedRectPath } from '../_chart/paths';
   import type { LegendItem, BarRect } from '../_chart/types';
+  import { SvelteMap } from 'svelte/reactivity';
+
+  // ── Per-instance uid prefix for <defs> ids (A1-3) ─────────────
+  // Derived at module scope per the library uid pattern (e.g. AreaChart
+  // feat/linechart-gradient line 17) to prevent id collision across multiple
+  // BarChart instances on the same page.
+  const uid = Math.random().toString(36).slice(2, 9);
+
+  /** Returns the plain CSS fallback color for any BarFill (used for legend, aria-label). */
+  function fallbackColor(fill: BarFill, index: number): string {
+    if (typeof fill === 'string') {
+      return fill;
+    }
+    if ('pattern' in fill) {
+      return fill.pattern.color ?? getColor(index);
+    }
+    // gradient: use first stop color as fallback
+    const firstStop = fill.gradient.stops[0];
+    return firstStop?.color ?? getColor(index);
+  }
 
   // ── Props ──────────────────────────────────────────────────────
 
@@ -29,8 +56,12 @@
     yAxisLabel,
     yDomain,
     valueFormat,
+    stackNormalize = false,
+    scrollable = false,
+    minBandWidth = 48,
     tooltipSnippet,
     empty,
+    renderOverlay,
     onbarclick,
     onbarhover,
     testId,
@@ -60,17 +91,41 @@
     return first.map((d) => d.label);
   });
 
+  let isNormalized = $derived(stackNormalize && isMulti && groupMode === 'stacked');
+
+  /** When stackNormalize is active and no custom valueFormat is supplied, append % so the
+   *  unitless tick numbers (0, 25, 50, 75, 100) are displayed as percentages consistently
+   *  in tooltips and value labels. A consumer-supplied valueFormat always takes precedence. */
+  let normalizedFormat = $derived(
+    isNormalized && valueFormat == null ? (v: number) => `${formatNumber(v)}%` : format
+  );
+
+  // ── Y-extent: account for floating bars (A1-1) ────────────────
+
   let yExtent = $derived.by<[number, number]>(() => {
     if (yDomain) {
       return yDomain;
     }
     if (isMulti && groupMode === 'stacked') {
-      const totalsPerLabel = labels.map((_, i) =>
-        resolvedSeries.reduce((sum, s) => sum + Math.max(0, s.data[i]?.value ?? 0), 0)
+      if (stackNormalize) {
+        return [0, 100];
+      }
+      const totalsPerLabel = labels.map((_, labelIndex) =>
+        resolvedSeries.reduce((sum, s) => sum + Math.max(0, s.data[labelIndex]?.value ?? 0), 0)
       );
       return niceLinearDomain(0, Math.max(0, ...totalsPerLabel));
     }
-    const all = resolvedSeries.flatMap((s) => s.data.map((d) => d.value));
+    // Collect all individual values including floating-bar low/high endpoints
+    const all: number[] = [];
+    for (const s of resolvedSeries) {
+      for (const d of s.data) {
+        if (Array.isArray(d.range)) {
+          all.push(d.range[0], d.range[1]);
+        } else {
+          all.push(d.value);
+        }
+      }
+    }
     if (all.length === 0) {
       return [0, 1];
     }
@@ -84,59 +139,109 @@
     createLinearScale(yExtent, isVertical ? [dims.innerHeight, 0] : [0, dims.innerWidth])
   );
 
+  // ── Bar geometry (A1-1 floating bars integrated) ──────────────
+
   let bars = $derived.by<BarRect[]>(() => {
     const zeroPos = valScale(0);
     const result: BarRect[] = [];
 
+    /**
+     * Computes x/y/width/height for a single data point in vertical or
+     * horizontal orientation, handling both normal value bars and floating
+     * [low,high] range bars (A1-1).
+     */
+    const barGeometry = (
+      d: (typeof resolvedSeries)[0]['data'][0],
+      catPos: number,
+      barW: number
+    ): { x: number; y: number; width: number; height: number; isFloating: boolean } => {
+      const hasRange = Array.isArray(d.range);
+      if (isVertical) {
+        if (hasRange) {
+          const lowPos = valScale(d.range![0]);
+          const highPos = valScale(d.range![1]);
+          const top = Math.min(lowPos, highPos);
+          const bottom = Math.max(lowPos, highPos);
+          return {
+            x: catPos,
+            y: top,
+            width: barW,
+            height: Math.max(2, bottom - top),
+            isFloating: true
+          };
+        }
+        const valPos = valScale(d.value);
+        return {
+          x: catPos,
+          y: d.value >= 0 ? valPos : zeroPos,
+          width: barW,
+          height: Math.max(2, Math.abs(valPos - zeroPos)),
+          isFloating: false
+        };
+      } else {
+        if (hasRange) {
+          const lowPos = valScale(d.range![0]);
+          const highPos = valScale(d.range![1]);
+          const left = Math.min(lowPos, highPos);
+          const right = Math.max(lowPos, highPos);
+          return {
+            x: left,
+            y: catPos,
+            width: Math.max(2, right - left),
+            height: barW,
+            isFloating: true
+          };
+        }
+        const valPos = valScale(d.value);
+        return {
+          x: d.value >= 0 ? zeroPos : valPos,
+          y: catPos,
+          width: Math.max(2, Math.abs(valPos - zeroPos)),
+          height: barW,
+          isFloating: false
+        };
+      }
+    };
+
     if (isMulti && groupMode === 'grouped') {
       const subBand = catScale.bandwidth / resolvedSeries.length;
       for (let si = 0; si < resolvedSeries.length; si++) {
         const s = resolvedSeries[si];
-        const seriesColor = s.color ?? getColor(si);
+        const seriesFill: BarFill = s.color ?? getColor(si);
         for (let pi = 0; pi < s.data.length; pi++) {
           const d = s.data[pi];
           const catPos = catScale(d.label) + si * subBand;
-          const valPos = valScale(d.value);
-          const color = d.color ?? seriesColor;
-          result.push(
-            isVertical
-              ? {
-                  x: catPos,
-                  y: d.value >= 0 ? valPos : zeroPos,
-                  width: Math.max(1, subBand * 0.9),
-                  height: Math.max(2, Math.abs(valPos - zeroPos)),
-                  color,
-                  si,
-                  pi,
-                  dataPoint: d,
-                  seriesName: s.name
-                }
-              : {
-                  x: d.value >= 0 ? zeroPos : valPos,
-                  y: catPos,
-                  width: Math.max(2, Math.abs(valPos - zeroPos)),
-                  height: Math.max(1, subBand * 0.9),
-                  color,
-                  si,
-                  pi,
-                  dataPoint: d,
-                  seriesName: s.name
-                }
-          );
+          const barW = Math.max(1, subBand * 0.9);
+          const geom = barGeometry(d, catPos, barW);
+          const effectiveFill: BarFill = d.color ?? seriesFill;
+          const color = fallbackColor(effectiveFill, si);
+          const fillId = resolveFillId(effectiveFill, si, pi, d.color != null);
+          result.push({ ...geom, color, fillId, si, pi, dataPoint: d, seriesName: s.name });
         }
       }
     } else if (isMulti && groupMode === 'stacked') {
+      const categoryTotals = labels.map((_, labelIndex) =>
+        resolvedSeries.reduce((sum, s) => sum + Math.max(0, s.data[labelIndex]?.value ?? 0), 0)
+      );
       const stackBase = new Array(labels.length).fill(0);
       for (let si = 0; si < resolvedSeries.length; si++) {
         const s = resolvedSeries[si];
-        const seriesColor = s.color ?? getColor(si);
+        const seriesFill: BarFill = s.color ?? getColor(si);
         for (let pi = 0; pi < s.data.length; pi++) {
           const d = s.data[pi];
-          const val = Math.max(0, d.value);
+          const rawVal = Math.max(0, d.value);
+          const normalizedValue = isNormalized
+            ? categoryTotals[pi] > 0
+              ? (rawVal / categoryTotals[pi]) * 100
+              : 0
+            : null;
+          const val = isNormalized ? (normalizedValue ?? 0) : rawVal;
           const y0 = stackBase[pi];
           const y1 = y0 + val;
           stackBase[pi] = y1;
-          const color = d.color ?? seriesColor;
+          const effectiveFill: BarFill = d.color ?? seriesFill;
+          const color = fallbackColor(effectiveFill, si);
+          const fillId = resolveFillId(effectiveFill, si, pi, d.color != null);
           if (isVertical) {
             result.push({
               x: catScale(d.label),
@@ -144,10 +249,13 @@
               width: catScale.bandwidth,
               height: Math.max(0, valScale(y0) - valScale(y1)),
               color,
+              fillId,
               si,
               pi,
               dataPoint: d,
-              seriesName: s.name
+              seriesName: s.name,
+              normalizedValue,
+              isFloating: false
             });
           } else {
             result.push({
@@ -156,10 +264,13 @@
               width: Math.max(0, valScale(y1) - valScale(y0)),
               height: catScale.bandwidth,
               color,
+              fillId,
               si,
               pi,
               dataPoint: d,
-              seriesName: s.name
+              seriesName: s.name,
+              normalizedValue,
+              isFloating: false
             });
           }
         }
@@ -169,44 +280,128 @@
       for (let pi = 0; pi < singleSeries.data.length; pi++) {
         const d = singleSeries.data[pi];
         const catPos = catScale(d.label);
-        const valPos = valScale(d.value);
-        const color = d.color ?? getColor(pi);
-        result.push(
-          isVertical
-            ? {
-                x: catPos,
-                y: d.value >= 0 ? valPos : zeroPos,
-                width: catScale.bandwidth,
-                height: Math.max(2, Math.abs(valPos - zeroPos)),
-                color,
-                si: 0,
-                pi,
-                dataPoint: d,
-                seriesName: singleSeries.name
-              }
-            : {
-                x: d.value >= 0 ? zeroPos : valPos,
-                y: catPos,
-                width: Math.max(2, Math.abs(valPos - zeroPos)),
-                height: catScale.bandwidth,
-                color,
-                si: 0,
-                pi,
-                dataPoint: d,
-                seriesName: singleSeries.name
-              }
-        );
+        const barW = catScale.bandwidth;
+        const geom = barGeometry(d, catPos, barW);
+        const effectiveFill: BarFill = d.color ?? singleSeries.color ?? getColor(pi);
+        const color = fallbackColor(effectiveFill, pi);
+        const fillId = resolveFillId(effectiveFill, 0, pi, d.color != null);
+        result.push({
+          ...geom,
+          color,
+          fillId,
+          si: 0,
+          pi,
+          dataPoint: d,
+          seriesName: singleSeries.name
+        });
       }
     }
     return result;
   });
 
+  // ── Defs: pattern and gradient fill resolution (A1-2 / A1-3) ──
+
+  /**
+   * Computes a stable defs element id for a given bar fill.
+   *
+   * Series-level fills (no per-bar override) share ONE def entry keyed by `si`
+   * only, so N data points in the same series do not produce N duplicate SVG
+   * ids. Per-bar fills (d.color is set) include `pi` so each bar gets its own
+   * def. Returns null for plain CSS color strings (no defs entry needed).
+   */
+  function resolveFillId(fill: BarFill, si: number, pi: number, isPerBar: boolean): string | null {
+    if (typeof fill === 'string') {
+      return null;
+    }
+    const key = isPerBar ? `${si}-${pi}` : `${si}`;
+    if ('pattern' in fill) {
+      return `${uid}-pat-${key}`;
+    }
+    if ('gradient' in fill) {
+      return `${uid}-grad-${key}`;
+    }
+    return null;
+  }
+
+  /**
+   * Collects unique defs entries (pattern or gradient fills) needed by the
+   * current set of bars. Uses a SvelteMap keyed by id to guarantee each SVG id
+   * is emitted exactly once — series-level fills that apply to many bars collapse
+   * to a single shared def, satisfying the SVG uniqueness requirement.
+   */
+  let defsEntries = $derived.by(() => {
+    const seen = new SvelteMap<
+      string,
+      { id: string; bar: BarRect; fill: BarFillPattern | BarFillGradient }
+    >();
+    for (const bar of bars) {
+      if (!bar.fillId) {
+        continue;
+      }
+      if (seen.has(bar.fillId)) {
+        continue;
+      }
+      const rawFill = bar.dataPoint.color ?? resolvedSeries[bar.si]?.color;
+      if (rawFill == null || typeof rawFill === 'string') {
+        continue;
+      }
+      if ('pattern' in rawFill || 'gradient' in rawFill) {
+        seen.set(bar.fillId, { id: bar.fillId, bar, fill: rawFill });
+      }
+    }
+    return [...seen.values()];
+  });
+
+  // ── Legend items ───────────────────────────────────────────────
+
   let legendItems = $derived<LegendItem[]>(
-    isMulti ? resolvedSeries.map((s, i) => ({ label: s.name, color: s.color ?? getColor(i) })) : []
+    isMulti
+      ? resolvedSeries.map((s, i) => ({
+          label: s.name,
+          color: fallbackColor(s.color ?? getColor(i), i)
+        }))
+      : []
   );
 
   let isEmpty = $derived(resolvedSeries.every((s) => s.data.length === 0) || labels.length === 0);
 
+  // ── Scroll geometry ────────────────────────────────────────────
+
+  let minScrollWidth = $derived(
+    labels.length * minBandWidth + dims.margin.left + dims.margin.right
+  );
+
+  // ── Stacked bar path helper ────────────────────────────────────
+
+  let lastSeriesIndex = $derived(resolvedSeries.length - 1);
+
+  function stackedBarPath(bar: BarRect): string {
+    if (barRadius <= 0) {
+      return roundedRectPath(bar.x, bar.y, bar.width, bar.height, 0, 0, 0, 0);
+    }
+    const isFirst = bar.si === 0;
+    const isLast = bar.si === lastSeriesIndex;
+    if (isVertical) {
+      const tl = isLast ? barRadius : 0;
+      const tr = isLast ? barRadius : 0;
+      const br = isFirst ? barRadius : 0;
+      const bl = isFirst ? barRadius : 0;
+      return roundedRectPath(bar.x, bar.y, bar.width, bar.height, tl, tr, br, bl);
+    } else {
+      const tl = isFirst ? barRadius : 0;
+      const bl = isFirst ? barRadius : 0;
+      const tr = isLast ? barRadius : 0;
+      const br = isLast ? barRadius : 0;
+      return roundedRectPath(bar.x, bar.y, bar.width, bar.height, tl, tr, br, bl);
+    }
+  }
+
+  // ── Fill attribute helper ──────────────────────────────────────
+
+  function barFillAttr(bar: BarRect): string {
+    return bar.fillId ? `url(#${bar.fillId})` : bar.color;
+  }
+
   // ── Tooltip ────────────────────────────────────────────────────
 
   let tooltipData = $derived.by(() => {
@@ -218,12 +413,29 @@
       return null;
     }
     const title = isMulti ? `${bar.dataPoint.label} — ${bar.seriesName}` : bar.dataPoint.label;
+    const displayValue =
+      isNormalized && bar.normalizedValue != null
+        ? normalizedFormat(bar.normalizedValue)
+        : format(bar.dataPoint.value);
     return {
       title,
-      items: [{ label: bar.dataPoint.label, value: format(bar.dataPoint.value), color: bar.color }]
+      items: [{ label: bar.dataPoint.label, value: displayValue, color: bar.color }]
     };
   });
 
+  // ── Render context for overlay snippet (A1-4) ─────────────────
+
+  let overlayContext = $derived<BarChartRenderContext>({
+    innerWidth: dims.innerWidth,
+    innerHeight: dims.innerHeight,
+    margin: {
+      top: dims.margin.top,
+      right: dims.margin.right,
+      bottom: dims.margin.bottom,
+      left: dims.margin.left
+    }
+  });
+
   // ── Interactions ───────────────────────────────────────────────
 
   function trackMouse(e: MouseEvent) {
@@ -255,6 +467,18 @@
       ? null
       : (bars.find((b) => b.si === hovered!.si && b.pi === hovered!.pi) ?? null);
   }
+
+  let isStackedMode = $derived(isMulti && groupMode === 'stacked');
+
+  function getDisplayValue(bar: BarRect): string {
+    if (isNormalized && bar.normalizedValue != null) {
+      return normalizedFormat(bar.normalizedValue);
+    }
+    if (bar.isFloating && Array.isArray(bar.dataPoint.range)) {
+      return `${format(bar.dataPoint.range[0])} – ${format(bar.dataPoint.range[1])}`;
+    }
+    return format(bar.dataPoint.value);
+  }
 </script>
 
 <div
@@ -269,61 +493,178 @@
       <Legend items={legendItems} position="top" />
     {/if}
 
-    <ChartContainer bind:width={chartWidth} bind:height={chartHeight} {aspectRatio}>
-      <g transform="translate({dims.margin.left}, {dims.margin.top})">
-        {#if showYAxis}
-          <Axis
-            orientation="left"
-            scale={isVertical ? valScale : catScale}
-            {showGridlines}
-            gridlineLength={dims.innerWidth}
-            label={yAxisLabel}
-          />
-        {/if}
-        {#if showXAxis}
-          <g transform="translate(0, {dims.innerHeight})">
-            <Axis
-              orientation="bottom"
-              scale={isVertical ? catScale : valScale}
-              showGridlines={!isVertical && showGridlines}
-              gridlineLength={dims.innerHeight}
-              label={xAxisLabel}
-            />
-          </g>
-        {/if}
-
-        {#each bars as bar, i (i)}
-          <!-- svelte-ignore a11y_no_static_element_interactions -->
-          <!-- svelte-ignore a11y_click_events_have_key_events -->
-          <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={bar.color}
-            aria-label="{bar.dataPoint.label}: {format(bar.dataPoint.value)}"
-            onmouseenter={(e) => handleEnter(e, bar)}
-            onmousemove={trackMouse}
-            onmouseleave={handleLeave}
-            onclick={() => handleClick(bar)}
-          />
-          {#if showValues && !(isMulti && groupMode === 'stacked')}
-            <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'}>{format(bar.dataPoint.value)}</text
-            >
+    <!-- svelte-ignore a11y_no_noninteractive_tabindex -->
+    <div
+      class="chart-scroll-area"
+      role="region"
+      aria-label={yAxisLabel ? `${yAxisLabel} bar chart` : 'Bar chart'}
+      tabindex={scrollable ? 0 : null}
+      style={scrollable
+        ? `overflow-x: auto; -webkit-overflow-scrolling: touch; height: var(--barchart-scroll-area-height, auto);`
+        : ''}
+    >
+      <div style={scrollable ? `min-width: ${minScrollWidth}px;` : ''}>
+        <ChartContainer bind:width={chartWidth} bind:height={chartHeight} {aspectRatio}>
+          <!-- A1-2 / A1-3: SVG <defs> for pattern and gradient fills -->
+          {#if defsEntries.length > 0}
+            <defs>
+              {#each defsEntries as entry (entry.id)}
+                {#if 'pattern' in entry.fill}
+                  {@const pat = entry.fill.pattern}
+                  {@const patSize = pat.size ?? 8}
+                  {@const patColor = pat.color ?? entry.bar.color}
+                  {@const patBg = pat.background ?? 'transparent'}
+                  {@const patStrokeW = pat.strokeWidth ?? 1.5}
+                  <pattern
+                    id={entry.id}
+                    patternUnits="userSpaceOnUse"
+                    width={patSize}
+                    height={patSize}
+                  >
+                    <rect width={patSize} height={patSize} fill={patBg} />
+                    {#if pat.type === 'lines'}
+                      <line
+                        x1="0"
+                        y1={patSize}
+                        x2={patSize}
+                        y2="0"
+                        stroke={patColor}
+                        stroke-width={patStrokeW}
+                      />
+                    {:else if pat.type === 'crosshatch'}
+                      <line
+                        x1="0"
+                        y1={patSize}
+                        x2={patSize}
+                        y2="0"
+                        stroke={patColor}
+                        stroke-width={patStrokeW}
+                      />
+                      <line
+                        x1="0"
+                        y1="0"
+                        x2={patSize}
+                        y2={patSize}
+                        stroke={patColor}
+                        stroke-width={patStrokeW}
+                      />
+                    {:else}
+                      <!-- dots -->
+                      <circle cx={patSize / 2} cy={patSize / 2} r={patStrokeW} fill={patColor} />
+                    {/if}
+                  </pattern>
+                {:else if 'gradient' in entry.fill}
+                  {@const grad = entry.fill.gradient}
+                  {@const isHoriz = grad.direction === 'horizontal'}
+                  <!--
+                    gradientUnits="userSpaceOnUse" is required here.
+                    objectBoundingBox ratios are undefined on degenerate (zero-height)
+                    path bounding boxes (stacked segments, Firefox renders black).
+                    userSpaceOnUse resolves in the coordinate system of the
+                    referencing element — i.e. inner space (inside the <g transform>)
+                    — so bar.y / bar.x / bar.height / bar.width are used directly
+                    without any margin offset. This matches the AreaChart pattern
+                    (feat/linechart-gradient ea5f794, lines 282-284).
+                  -->
+                  <linearGradient
+                    id={entry.id}
+                    x1={entry.bar.x}
+                    y1={entry.bar.y}
+                    x2={isHoriz ? entry.bar.x + entry.bar.width : entry.bar.x}
+                    y2={isHoriz ? entry.bar.y : entry.bar.y + entry.bar.height}
+                    gradientUnits="userSpaceOnUse"
+                  >
+                    {#each grad.stops as stop (stop.offset)}
+                      <stop
+                        offset="{stop.offset * 100}%"
+                        stop-color={stop.color}
+                        stop-opacity={stop.opacity ?? 1}
+                      />
+                    {/each}
+                  </linearGradient>
+                {/if}
+              {/each}
+            </defs>
           {/if}
-        {/each}
-      </g>
-    </ChartContainer>
+
+          <g transform="translate({dims.margin.left}, {dims.margin.top})">
+            {#if showYAxis}
+              <Axis
+                orientation="left"
+                scale={isVertical ? valScale : catScale}
+                {showGridlines}
+                gridlineLength={dims.innerWidth}
+                label={yAxisLabel}
+              />
+            {/if}
+            {#if showXAxis}
+              <g transform="translate(0, {dims.innerHeight})">
+                <Axis
+                  orientation="bottom"
+                  scale={isVertical ? catScale : valScale}
+                  showGridlines={!isVertical && showGridlines}
+                  gridlineLength={dims.innerHeight}
+                  label={xAxisLabel}
+                />
+              </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}
+
+            <!-- A1-4: renderOverlay escape hatch — rendered after all bars -->
+            {#if typeof renderOverlay === 'function'}
+              {@render renderOverlay(overlayContext)}
+            {/if}
+          </g>
+        </ChartContainer>
+      </div>
+    </div>
 
     {#if typeof tooltipSnippet === 'function' && hoveredBar()}
       {@const hb = hoveredBar()}
@@ -343,6 +684,9 @@
     width: 100%;
     position: relative;
   }
+  .chart-scroll-area {
+    width: 100%;
+  }
   .bar {
     transition: opacity var(--chart-transition-duration, 0.2s) ease;
     cursor: pointer;

package/dist/BarChart/properties.d.ts

@@ -1,13 +1,69 @@
 import type { Snippet } from 'svelte';
+export type BarFillPattern = {
+    pattern: {
+        /** SVG pattern element type: 'lines' | 'dots' | 'crosshatch' */
+        type: 'lines' | 'dots' | 'crosshatch';
+        /** Foreground stroke/fill color of the pattern marks */
+        color?: string;
+        /** Background fill color (defaults to transparent) */
+        background?: string;
+        /** Pattern cell size in px (default 8) */
+        size?: number;
+        /** Stroke width for line-based patterns (default 1.5) */
+        strokeWidth?: number;
+    };
+};
+export type BarFillGradientStop = {
+    offset: number;
+    color: string;
+    opacity?: number;
+};
+export type BarFillGradient = {
+    gradient: {
+        stops: BarFillGradientStop[];
+        /** 'vertical' → top-to-bottom (default), 'horizontal' → left-to-right */
+        direction?: 'vertical' | 'horizontal';
+    };
+};
+/** A bar's fill: plain CSS color string, SVG pattern fill, or linear gradient fill. */
+export type BarFill = string | BarFillPattern | BarFillGradient;
 export type BarChartDataPoint = {
     label: string;
+    /** Value used for a standard bar. Ignored when [low, high] tuple is supplied. */
     value: number;
-    color?: string;
+    /**
+     * A1-1 floating / columnrange bar: [low, high] tuple where both are absolute
+     * domain values. When present the bar spans from low to high instead of
+     * from zero to value.
+     */
+    range?: [number, number];
+    /** Per-bar fill: plain color, pattern, or gradient. Overrides series color. */
+    color?: BarFill;
 };
 export type BarChartSeries = {
     name: string;
     data: BarChartDataPoint[];
-    color?: string;
+    /** Series-level fill: plain color, pattern, or gradient. */
+    color?: BarFill;
+};
+export type BarChartRenderContext = {
+    /** Inner drawing width (pixels) */
+    innerWidth: number;
+    /** Inner drawing height (pixels) */
+    innerHeight: number;
+    /**
+     * Full margin offsets applied to the main <g> transform.
+     * All four edges are exposed so consumers can compute chart
+     * boundaries in both dimensions (e.g. innerWidth + margin.right
+     * for a right-edge annotation, innerHeight + margin.bottom for
+     * a bottom-edge connector in a funnel overlay).
+     */
+    margin: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
 };
 export type BarChartProperties = OptionalBarChartProperties & BarChartEventProperties;
 export type OptionalBarChartProperties = {
@@ -27,8 +83,35 @@ export type OptionalBarChartProperties = {
     valueFormat?: (value: number) => string;
     groupMode?: 'grouped' | 'stacked';
     showLegend?: boolean;
+    /**
+     * When `true` and `groupMode="stacked"`, normalises each category's stack to
+     * 100% so bars represent proportions rather than absolute values. The Y axis
+     * runs 0–100 and value labels are suffixed with `%` (unless `valueFormat` is
+     * provided to override the default formatter).
+     */
+    stackNormalize?: boolean;
+    /**
+     * When `true`, wraps the SVG in a horizontally-scrollable container so that
+     * wide charts with many categories remain readable at small container widths.
+     * Combine with `minBandWidth` to control how much each category band expands
+     * before the chart begins to overflow and scroll.
+     */
+    scrollable?: boolean;
+    /**
+     * Minimum pixel width per category band when `scrollable` is `true`.
+     * The chart's inner width grows until every band is at least this many pixels
+     * wide, then the scroll container takes over. Has no effect when `scrollable`
+     * is `false`. Default is `48`.
+     */
+    minBandWidth?: number;
     tooltipSnippet?: Snippet<[BarChartDataPoint, number]>;
     empty?: Snippet;
+    /**
+     * A1-4 escape hatch: a Snippet rendered inside the SVG transform group after
+     * all bars. Use for overlays, annotations, or drop-off indicators that must
+     * live in SVG coordinate space.
+     */
+    renderOverlay?: Snippet<[BarChartRenderContext]>;
     testId?: string;
     classes?: string;
 };

package/dist/SankeyChart/SankeyChart.svelte

@@ -5,7 +5,7 @@
   import { computeSankeyLayout } from '../_chart/geometry';
   import { getColor } from '../_chart/colors';
   import { formatNumber } from '../_chart/format';
-  import { SvelteSet } from 'svelte/reactivity';
+  import { SvelteMap, SvelteSet } from 'svelte/reactivity';
 
   // ── Props ──────────────────────────────────────────────────────
 
@@ -26,7 +26,9 @@
     onnodehover,
     onlinkhover,
     testId,
-    classes
+    classes,
+    columnLabels,
+    nodeColorResolver
   }: SankeyChartProperties = $props();
 
   // ── State ──────────────────────────────────────────────────────
@@ -56,6 +58,45 @@
     )
   );
 
+  /**
+   * Pre-computed colour map for all nodes. Keyed by node id. Computed once per layout
+   * change rather than re-running find() + indexOf() for every link on every render.
+   *
+   * Note: nodeColorResolver also controls link stroke colours (links inherit source-node
+   * colour), not just node fill colours. See Props docs for full description.
+   */
+  let nodeColorMap = $derived.by(() => {
+    const map = new SvelteMap<string, string>();
+    for (let ni = 0; ni < layout.nodes.length; ni++) {
+      const node = layout.nodes[ni];
+      const color = node.color ?? nodeColorResolver?.(node.id, node.label ?? null) ?? getColor(ni);
+      map.set(node.id, color);
+    }
+    return map;
+  });
+
+  // Column count and width — used by columnLabels rendering
+  let columnCount = $derived(
+    layout.nodes.length > 0 ? Math.max(...layout.nodes.map((n) => n.column)) + 1 : 0
+  );
+  let colWidth = $derived(
+    columnCount <= 1
+      ? Math.max(0, chartWidth - MARGIN * 2)
+      : (Math.max(0, chartWidth - MARGIN * 2) - nodeWidth) / (columnCount - 1)
+  );
+
+  // ── Helpers ────────────────────────────────────────────────────
+
+  /** Percentage of source node's total value carried by a link (0–100, 2 dp). */
+  const computeLinkPct = (sourceId: string, linkValue: number): number => {
+    const sourceNode = layout.nodes.find((nd) => nd.id === sourceId);
+    if (!sourceNode) {
+      return 0;
+    }
+    const sourceTotal = sourceNode.value;
+    return sourceTotal > 0 ? Math.round((linkValue / sourceTotal) * 10000) / 100 : 0;
+  };
+
   let connectedNodes = $derived.by(() => {
     if (hoveredNode !== null) {
       const connected = new SvelteSet<string>([hoveredNode]);
@@ -75,6 +116,27 @@
 
   // ── Tooltip ────────────────────────────────────────────────────
 
+  /**
+   * Pre-computed link tooltip data for the currently hovered link. Computed once and shared
+   * by both `tooltipData` and `tooltipContext` to avoid running the O(n) percentage lookup
+   * twice on every hover state change.
+   */
+  let hoveredLinkCache = $derived.by(() => {
+    if (hoveredLink === null) {
+      return null;
+    }
+    const l = links.find(
+      (lk) => lk.source === hoveredLink!.source && lk.target === hoveredLink!.target
+    );
+    if (!l) {
+      return null;
+    }
+    const sourceLabelText = nodes.find((nd) => nd.id === l.source)?.label ?? l.source;
+    const targetLabelText = nodes.find((nd) => nd.id === l.target)?.label ?? l.target;
+    const pct = computeLinkPct(l.source, l.value);
+    return { link: l, sourceLabel: sourceLabelText, targetLabel: targetLabelText, percentage: pct };
+  });
+
   let tooltipData = $derived.by(() => {
     if (hoveredNode !== null) {
       const n = layout.nodes.find((nd) => nd.id === hoveredNode);
@@ -92,16 +154,14 @@
         ]
       };
     }
-    if (hoveredLink !== null) {
-      const l = links.find(
-        (lk) => lk.source === hoveredLink!.source && lk.target === hoveredLink!.target
-      );
-      if (!l) {
-        return null;
-      }
+    if (hoveredLinkCache !== null) {
+      const { link: l, sourceLabel, targetLabel, percentage: pct } = hoveredLinkCache;
       return {
-        title: `${nodes.find((n) => n.id === l.source)?.label ?? l.source} → ${nodes.find((n) => n.id === l.target)?.label ?? l.target}`,
-        items: [{ label: 'Flow', value: format(l.value) }]
+        title: `${sourceLabel} → ${targetLabel}`,
+        items: [
+          { label: 'Flow', value: format(l.value) },
+          { label: 'of source', value: `${pct.toFixed(2)}%` }
+        ]
       };
     }
     return null;
@@ -116,12 +176,15 @@
       }
       return { type: 'node', node: n, value: computed.value };
     }
-    if (hoveredLink !== null) {
-      const l = findLink(hoveredLink.source, hoveredLink.target);
-      if (!l) {
-        return null;
-      }
-      return { type: 'link', link: l };
+    if (hoveredLinkCache !== null) {
+      const { link: l, sourceLabel, targetLabel, percentage: pct } = hoveredLinkCache;
+      return {
+        type: 'link',
+        link: l,
+        sourceLabel,
+        targetLabel,
+        percentage: pct
+      };
     }
     return null;
   });
@@ -208,6 +271,18 @@
   {:else}
     <ChartContainer bind:width={chartWidth} bind:height={chartHeight} {aspectRatio}>
       <g transform="translate({MARGIN}, {MARGIN})">
+        {#if columnLabels != null && columnLabels.length > 0}
+          {#each columnLabels as label, ci (ci)}
+            <text
+              class="sankey-col-label"
+              x={ci * colWidth + nodeWidth / 2}
+              y={-8}
+              text-anchor="middle"
+              dominant-baseline="auto">{label}</text
+            >
+          {/each}
+        {/if}
+
         {#each layout.links as link, i (i)}
           {@const highlighted = isLinkHighlighted(link.source, link.target)}
           {@const dimmed = (hoveredNode !== null || hoveredLink !== null) && !highlighted}
@@ -217,7 +292,7 @@
             class="sankey-link"
             d={link.path}
             fill="none"
-            stroke={link.color ?? getColor(layout.nodes.findIndex((n) => n.id === link.source))}
+            stroke={link.color ?? nodeColorMap.get(link.source) ?? getColor(0)}
             stroke-width={Math.max(1, link.width)}
             stroke-opacity={highlighted ? 0.7 : dimmed ? 0.08 : 0.4}
             onmouseenter={(e) => handleLinkEnter(e, link.source, link.target)}
@@ -228,7 +303,7 @@
         {/each}
 
         {#each layout.nodes as node, ni (ni)}
-          {@const color = node.color ?? getColor(ni)}
+          {@const color = nodeColorMap.get(node.id) ?? getColor(ni)}
           {@const dimmed = connectedNodes !== null && !connectedNodes.has(node.id)}
           <!-- svelte-ignore a11y_no_static_element_interactions -->
           <!-- svelte-ignore a11y_click_events_have_key_events -->
@@ -296,6 +371,12 @@
     pointer-events: none;
     transition: opacity var(--chart-transition-duration, 0.2s) ease;
   }
+  .sankey-col-label {
+    fill: var(--sankey-col-label-color, #666);
+    font-size: var(--sankey-col-label-font-size, 11px);
+    font-family: var(--chart-font-family, inherit);
+    pointer-events: none;
+  }
   .sankey-label.node-dimmed {
     opacity: var(--sankey-dimmed-opacity, 0.15);
   }

package/dist/SankeyChart/properties.d.ts

@@ -10,6 +10,14 @@ export type SankeyLink = {
     value: number;
     color?: string;
 };
+/**
+ * Context passed to the `tooltipSnippet` prop on each hover event.
+ *
+ * The `'link'` branch gained three new optional fields (`sourceLabel`, `targetLabel`,
+ * `percentage`) in this release. They are always populated by the chart — the fields are
+ * typed optional so that existing consumer code that typed a variable explicitly as
+ * `{ type: 'link'; link: SankeyLink }` continues to compile without changes.
+ */
 export type SankeyTooltipContext = {
     type: 'node';
     node: SankeyNode;
@@ -17,6 +25,12 @@ export type SankeyTooltipContext = {
 } | {
     type: 'link';
     link: SankeyLink;
+    /** Human-readable label of the source node (falls back to node id when label is undefined). Always present at runtime. */
+    sourceLabel?: string;
+    /** Human-readable label of the target node (falls back to node id when label is undefined). Always present at runtime. */
+    targetLabel?: string;
+    /** link.value as a percentage of the source node's total outgoing value (0–100, rounded to 2 dp). Always present at runtime. */
+    percentage?: number;
 };
 export type SankeyChartProperties = MandatorySankeyChartProperties & OptionalSankeyChartProperties & SankeyChartEventProperties;
 export type MandatorySankeyChartProperties = {
@@ -35,6 +49,14 @@ export type OptionalSankeyChartProperties = {
     empty?: Snippet;
     testId?: string;
     classes?: string;
+    /** Labels rendered above each column, indexed by column position (0-based). */
+    columnLabels?: string[];
+    /**
+     * Called for each node and also for link strokes (links inherit the resolved source-node
+     * colour). Return a CSS colour string to override the default palette, or `null` to fall
+     * through to the default palette colour.
+     */
+    nodeColorResolver?: (id: string, label: string | null) => string | null;
 };
 export type SankeyChartEventProperties = {
     onnodeclick?: (event: {

package/dist/_chart/paths.d.ts

@@ -2,3 +2,10 @@ import type { Point, CurveType } from './types';
 export declare function arcPath(cx: number, cy: number, innerR: number, outerR: number, startAngle: number, endAngle: number): string;
 export declare function linePath(points: Point[], curve?: CurveType): string;
 export declare function areaPath(points: Point[], baseline: number, curve?: CurveType): string;
+/**
+ * Builds an SVG path string for a rectangle with independently-controlled
+ * corner radii. Each radius is clamped to Math.min(r, w/2, h/2) so the
+ * shape never degenerates. Parameters follow the CSS border-radius order:
+ * tl=top-left, tr=top-right, br=bottom-right, bl=bottom-left.
+ */
+export declare function roundedRectPath(x: number, y: number, w: number, h: number, tl: number, tr: number, br: number, bl: number): string;

package/dist/_chart/paths.js

@@ -136,3 +136,25 @@ export function areaPath(points, baseline, curve = 'linear') {
     const firstPoint = points[0];
     return topPath + ` L ${lastPoint.x} ${baseline} L ${firstPoint.x} ${baseline} Z`;
 }
+/**
+ * Builds an SVG path string for a rectangle with independently-controlled
+ * corner radii. Each radius is clamped to Math.min(r, w/2, h/2) so the
+ * shape never degenerates. Parameters follow the CSS border-radius order:
+ * tl=top-left, tr=top-right, br=bottom-right, bl=bottom-left.
+ */
+export function roundedRectPath(x, y, w, h, tl, tr, br, bl) {
+    const clamp = (r) => Math.min(r, w / 2, h / 2);
+    const rtl = clamp(tl);
+    const rtr = clamp(tr);
+    const rbr = clamp(br);
+    const rbl = clamp(bl);
+    return (`M ${x + rtl} ${y}` +
+        ` H ${x + w - rtr}` +
+        ` Q ${x + w} ${y} ${x + w} ${y + rtr}` +
+        ` V ${y + h - rbr}` +
+        ` Q ${x + w} ${y + h} ${x + w - rbr} ${y + h}` +
+        ` H ${x + rbl}` +
+        ` Q ${x} ${y + h} ${x} ${y + h - rbl}` +
+        ` V ${y + rtl}` +
+        ` Q ${x} ${y} ${x + rtl} ${y} Z`);
+}

package/dist/_chart/types.d.ts

@@ -71,11 +71,24 @@ export type BarRect = {
     y: number;
     width: number;
     height: number;
+    /**
+     * Resolved CSS color string used for plain fills and as the fallback when
+     * a defs-based fill (pattern / gradient) is in use.
+     */
     color: string;
+    /**
+     * When non-null, the bar's `fill` attribute should reference `url(#<fillId>)`
+     * instead of the plain `color` string. Set by the BarChart defs resolution
+     * logic for pattern and gradient fills.
+     */
+    fillId: string | null;
     si: number;
     pi: number;
     dataPoint: BarChartDataPoint;
     seriesName: string;
+    normalizedValue?: number | null;
+    /** True when this bar was produced from a [low, high] range tuple (A1-1). */
+    isFloating?: boolean;
 };
 export type StackedPoint = {
     x: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/svelte-ui-components",
-  "version": "2.57.0",
+  "version": "2.59.0",
   "description": "A themeable Svelte 5 UI component library with CSS custom property driven styling",
   "keywords": [
     "svelte",