@juspay/svelte-ui-components 4.20.0 → 4.22.0

package/dist/_chart/narrationHighlighter.d.ts

@@ -0,0 +1,83 @@
+import type { ChartHighlightAPI } from './highlight';
+/**
+ * Drives a chart's highlight from a growing narration transcript.
+ *
+ * `LineChart`, `BarChart` and `PieChart` hand back a `ChartHighlightAPI` from
+ * `onChartReady`, described there as being "for imperative point highlighting
+ * from external orchestrators (e.g. voice narration sync, step-through
+ * animations)". The socket shipped; the plug did not, so the obvious consumer —
+ * an assistant speaking over a chart — hand-rolled it, together with a registry
+ * of charts and a store of pending highlights.
+ *
+ * None of that is needed here. `getCategories()` is already the label list a
+ * registry would have duplicated, and `highlight(null)` is already the clear
+ * path, so this holds one `ChartHighlightAPI` and nothing else. Passing the API
+ * straight in also removes a race the registry version had to work around: a
+ * registry keyed by chart identity has to tolerate `onChartReady` firing before
+ * the chart is registered, which is a window that does not exist when the
+ * caller simply hands over the object it was given.
+ *
+ * ```ts
+ * let highlighter: NarrationHighlighter | null = null;
+ *
+ * <LineChart {data} onChartReady={(chart) => {
+ *   highlighter = createNarrationHighlighter({ chart });
+ * }} />
+ *
+ * // as each transcript chunk arrives
+ * highlighter?.processText(transcriptSoFar);
+ * // when the assistant starts a new answer
+ * highlighter?.reset();
+ * ```
+ */
+export type NarrationHighlighterOptions = {
+    /** The API handed to `onChartReady` by the chart being narrated. */
+    chart: ChartHighlightAPI;
+    /** Milliseconds a highlight stays up before clearing. Defaults to `2000`. */
+    autoClearMs?: number;
+    /** Match category labels case-sensitively. Defaults to `false`. */
+    caseSensitive?: boolean;
+    /**
+     * Replaces the built-in matching rule. Receives the narration and one
+     * category label, already lower-cased unless `caseSensitive` is set.
+     *
+     * The default matches a label only as a whole word. Substring matching is
+     * available through this hook — `(narration, category) =>
+     * narration.includes(category)` — but is a poor default: category labels are
+     * frequently ordinary words like `Other`, `All` or `None`, especially when
+     * they come from a model's tool output rather than a curated list, and a
+     * substring rule fires `Other` on `otherwise` and `others`.
+     *
+     * Whole-word matching narrows that surface; it does not close it. In "on the
+     * other hand", `other` is genuinely a standalone word, so the label still
+     * matches and no lexical rule could decide otherwise without reading the
+     * sentence. A caller who cannot curate labels should require something
+     * stronger here, and should `reset()` between turns so a mis-fire cannot
+     * outlive one answer.
+     */
+    match?: (narration: string, category: string) => boolean;
+};
+export type NarrationHighlighter = {
+    /**
+     * Reads the transcript so far and highlights the first not-yet-seen category
+     * it names. Returns that category's index, or `null` when the narration named
+     * nothing new.
+     *
+     * Safe to call on every chunk: the transcript is expected to grow, and a
+     * category already highlighted this turn is not highlighted again.
+     */
+    processText: (narration: string) => number | null;
+    /**
+     * Starts a new turn: clears the highlight and forgets which categories have
+     * fired, so they can fire again for the next answer.
+     */
+    reset: () => void;
+    /**
+     * Cancels a pending auto-clear. Call from the owner's teardown.
+     *
+     * Deliberately does not call into the chart: teardown ordering is the
+     * caller's, and the chart may already be gone.
+     */
+    destroy: () => void;
+};
+export declare const createNarrationHighlighter: (options: NarrationHighlighterOptions) => NarrationHighlighter;

package/dist/_chart/narrationHighlighter.js

@@ -0,0 +1,113 @@
+const DEFAULT_AUTO_CLEAR_MS = 2000;
+/** Letters, digits and underscore, so a label is matched only as a whole word. */
+const WORD_CHARACTER = /[\p{L}\p{N}_]/u;
+/**
+ * `charAt` rather than indexing: out of range it returns `''`, which is not a
+ * word character, so the string's edges need no special case.
+ */
+const isWordCharacter = (character) => WORD_CHARACTER.test(character);
+/**
+ * True when `needle` appears in `haystack` bounded by non-word characters.
+ *
+ * Written as a scan rather than a `RegExp` for two reasons: a category label is
+ * caller data and would have to be escaped, and `\b` is defined over ASCII word
+ * characters, so it mismatches labels like `Café` or `北区`. Lookbehind would
+ * solve the second but is not available everywhere this library runs.
+ */
+const occursAsWord = (haystack, needle) => {
+    for (let from = 0; from <= haystack.length - needle.length;) {
+        const at = haystack.indexOf(needle, from);
+        if (at === -1) {
+            return false;
+        }
+        const before = at === 0 ? '' : haystack.charAt(at - 1);
+        const after = haystack.charAt(at + needle.length);
+        if (!isWordCharacter(before) && !isWordCharacter(after)) {
+            return true;
+        }
+        from = at + 1;
+    }
+    return false;
+};
+/**
+ * The type says `number`, but a plain-JS or web-component caller can pass
+ * anything. `NaN` reaches `setTimeout` as an immediate fire, clearing the
+ * highlight before it has been seen, so an unusable delay degrades to the
+ * default rather than breaking the affordance it controls.
+ */
+const resolveAutoClearMs = (value) => {
+    if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
+        return DEFAULT_AUTO_CLEAR_MS;
+    }
+    return value;
+};
+/** `getCategories` is the chart's, and a torn-down chart can throw or return junk. */
+const readCategories = (chart) => {
+    try {
+        const categories = chart.getCategories();
+        if (!Array.isArray(categories)) {
+            return [];
+        }
+        return categories.flatMap((category, sourceIndex) => typeof category === 'string' ? [{ label: category, sourceIndex }] : []);
+    }
+    catch {
+        return [];
+    }
+};
+export const createNarrationHighlighter = (options) => {
+    const { chart, caseSensitive = false, match } = options;
+    const autoClearMs = resolveAutoClearMs(options.autoClearMs ?? null);
+    const fired = new Set();
+    let clearTimer = null;
+    const cancelPendingClear = () => {
+        if (clearTimer !== null) {
+            clearTimeout(clearTimer);
+            clearTimer = null;
+        }
+    };
+    const matches = (narration, category) => match ? match(narration, category) : occursAsWord(narration, category);
+    return {
+        processText: (narration) => {
+            if (typeof narration !== 'string' || narration.length === 0) {
+                return null;
+            }
+            const haystack = caseSensitive ? narration : narration.toLowerCase();
+            const categories = readCategories(chart);
+            /*
+             * Longest label wins. `Q1` is a whole-word match inside `Q1 Europe`, so
+             * taking the first hit would highlight the broader slice while the
+             * narration is naming the narrower one. Ties keep the earlier index,
+             * which makes the choice stable across calls.
+             */
+            let bestIndex = null;
+            let bestLength = 0;
+            categories.forEach(({ label, sourceIndex }) => {
+                if (label.length === 0 || fired.has(sourceIndex) || label.length <= bestLength) {
+                    return;
+                }
+                const needle = caseSensitive ? label : label.toLowerCase();
+                if (matches(haystack, needle)) {
+                    bestIndex = sourceIndex;
+                    bestLength = label.length;
+                }
+            });
+            if (bestIndex === null) {
+                return null;
+            }
+            fired.add(bestIndex);
+            cancelPendingClear();
+            chart.highlight(bestIndex);
+            clearTimer = setTimeout(() => {
+                clearTimer = null;
+                chart.highlight(null);
+            }, autoClearMs);
+            return bestIndex;
+        },
+        reset: () => {
+            cancelPendingClear();
+            fired.clear();
+            chart.highlight(null);
+        },
+        destroy: cancelPendingClear
+    };
+};

package/dist/_chart/types.d.ts

@@ -126,6 +126,14 @@ export type LegendItem = {
     color: string;
     /** True when the series is toggled off via an interactive legend. */
     hidden?: boolean;
+    /**
+     * Formatted per-series aggregate (e.g. `"$1.2K"`, `"45%"`) shown beside the
+     * label. `null`/omitted renders nothing -- both the "no `aggregate` was
+     * configured for this series" and "the series had no data to aggregate"
+     * cases resolve here, via `computeSeriesAggregate`/`formatSeriesAggregate`
+     * in `_chart/aggregate.ts`.
+     */
+    aggregateLabel?: string | null;
 };
 /** Data-space anchor for point/category-anchored tooltips (coords are container px). */
 export type TooltipAnchor = {

package/dist/index.d.ts

@@ -185,6 +185,7 @@ export type * from './ProportionBar/properties';
 export type * from './ChipInput/properties';
 export type * from './FileDropzoneTrigger/properties';
 export type * from './_chart/highlight';
+export type * from './_chart/narrationHighlighter';
 export type * from './Chat/properties';
 export type * from './Chat/types';
 export type * from './SpeechToText/types';
@@ -205,3 +206,4 @@ export type * from './Gallery/properties';
 export { createSoundKit } from './SoundKit/SoundKit';
 export { validateInput, lockBodyScroll, unlockBodyScroll } from './utils';
 export { formatNumberIndian } from './_chart/format';
+export { createNarrationHighlighter } from './_chart/narrationHighlighter';

package/dist/index.js

@@ -106,3 +106,4 @@ export { createCopyState } from './Snippet/copyState.svelte';
 export { createSoundKit } from './SoundKit/SoundKit';
 export { validateInput, lockBodyScroll, unlockBodyScroll } from './utils';
 export { formatNumberIndian } from './_chart/format';
+export { createNarrationHighlighter } from './_chart/narrationHighlighter';