@juspay/svelte-ui-components 4.30.0 → 4.31.1

package/dist/AnimatedNumber/AnimatedNumber.svelte

@@ -8,6 +8,7 @@
     locale = 'en-US',
     format,
     live = 'off',
+    animateOnMount = false,
     ariaLabel,
     testId,
     classes
@@ -397,7 +398,7 @@
         <span
           class="animated-number-digit"
           style="--_animated-number-digit: {column.digit};"
-          {@attach roll(column.digit, mounted, numeric)}
+          {@attach roll(column.digit, mounted || animateOnMount, numeric)}
         >
           {#each glyphs as glyph, index (glyph)}
             <!--
@@ -449,6 +450,64 @@
     color: var(--animated-number-color, inherit);
   }
 
+  /*
+   * The number renders as the text it replaced, even against a host stylesheet
+   * that styles bare elements.
+   *
+   * Every part of this component is a `<span>`: the root, the columns, the
+   * glyphs and the selection-copy node. A consumer carrying a bare `span` rule
+   * therefore hits all of them, and a type selector beats plain inheritance, so
+   * the number silently stopped matching its own label -- which is a text node
+   * in the parent and never affected.
+   *
+   * Measured rather than imagined: Lighthouse ships a bare `span` rule in
+   * static/style/text.css that sets colour, font-size and font-weight from its
+   * own tokens, and adopting the odometer there took every headline dashboard
+   * metric from 24px/600 to 12px/400 in the tertiary text colour, across nine
+   * routes. Nothing in this repo could have shown it: our own pages carry no
+   * such rule.
+   *
+   * Declared on the classes rather than left to inheritance so a bare type
+   * selector cannot win. `line-height` is deliberately NOT inherited -- the
+   * column box is this component's own geometry and is set below.
+   */
+  .animated-number,
+  .animated-number-plain,
+  .animated-number-visual,
+  .animated-number-digit,
+  .animated-number-digit-glyph,
+  .animated-number-literal {
+    font-family: inherit;
+    font-size: inherit;
+    font-weight: inherit;
+    font-style: inherit;
+    letter-spacing: inherit;
+  }
+
+  /*
+   * Colour is deliberately NOT in the group above, and the root is deliberately
+   * not in this one.
+   *
+   * The root already resolves its colour through the token, and that
+   * declaration sits EARLIER in this stylesheet. A grouped rule that also
+   * matched `.animated-number` would set `color: inherit` at equal specificity
+   * and later source order, so the token lost every time and the root silently
+   * took the parent's colour instead -- which is indistinguishable from the
+   * token working, because the token's own fallback IS `inherit`. Only a caller
+   * that actually set `--animated-number-color` would have seen it ignored.
+   *
+   * The descendants still need the explicit declaration: a bare `span` selector
+   * in a host stylesheet outranks plain inheritance, which is the whole reason
+   * this block exists.
+   */
+  .animated-number-plain,
+  .animated-number-visual,
+  .animated-number-digit,
+  .animated-number-digit-glyph,
+  .animated-number-literal {
+    color: inherit;
+  }
+
   .animated-number-visual {
     /* Decorative glyph content, same treatment Avatar, KeyboardInput, Tabs,
        Calendar and Draggable already give theirs. */
@@ -495,6 +554,21 @@
     margin-block: calc(-1 * var(--animated-number-fade-height, 0.28em));
   }
 
+  /*
+   * `inline-block` above makes every column its own inline formatting context,
+   * and collapsible whitespace at the edges of one of those is dropped -- so a
+   * literal column holding exactly one space measured zero wide and "12m 15s"
+   * painted as "12m15s". `pre` is the narrowest fix that keeps the space: it
+   * changes nothing for a literal that is not whitespace, and a column is a
+   * single character, so there is no wrapping behaviour to lose.
+   *
+   * Digits are exempt because they are never whitespace and their column has
+   * its own width.
+   */
+  .animated-number-literal {
+    white-space: pre;
+  }
+
   .animated-number-digit {
     position: relative;
     width: var(--animated-number-digit-width, 1ch);

package/dist/AnimatedNumber/properties.d.ts

@@ -33,6 +33,22 @@ export type OptionalAnimatedNumberProperties = {
      * @default 'off'
      */
     live?: AnimatedNumberLive;
+    /**
+     * Rolls every column up from zero when the number first appears, instead of
+     * painting it outright.
+     *
+     * Off by default, because a number that was always going to be on screen
+     * should not make the reader wait for it. Turn it on where the figure ARRIVES
+     * -- a dashboard whose metrics land after a fetch, a total that appears at the
+     * end of a flow -- and especially where the value then never changes again:
+     * without this, such a number is static for its whole life and the odometer
+     * does nothing at all.
+     *
+     * Independent of the rolls that follow. A later change animates either way,
+     * and this only governs the first paint.
+     * @default false
+     */
+    animateOnMount?: boolean;
     /** Overrides the accessible name, which otherwise mirrors the visible text. */
     ariaLabel?: string;
     /** Value for the `data-pw` attribute on the root element for E2E selection. */

package/dist/StatCard/StatCard.svelte

@@ -4,6 +4,7 @@
   import Tooltip from '../Tooltip/Tooltip.svelte';
   import CheckListItem from '../CheckListItem/CheckListItem.svelte';
   import AnimatedNumber from '../AnimatedNumber/AnimatedNumber.svelte';
+  import { isAnimatableMetric } from './metric';
 
   let {
     title,
@@ -14,6 +15,9 @@
     footer,
     valueSnippet,
     animateValue = false,
+    animatePrimary = false,
+    primary = 'auto',
+    animateOnMount = false,
     rows,
     rowsDirection = 'column',
     tooltip,
@@ -28,6 +32,99 @@
 
   const isInteractive = $derived(typeof onclick === 'function');
 
+  /**
+   * Which ONE value on this card rolls.
+   *
+   * A card has several numeric slots and they are not equally important. The
+   * business variant renders `subtitle` at 44px as the headline and its rows at
+   * 18-20px underneath, so animating "the values" animated the small ones and
+   * left the number the card is actually about sitting still -- backwards, and
+   * visible on every dashboard.
+   *
+   * `primary` resolves three ways so a caller can be as specific as it needs:
+   *   'auto'      measure the rendered slots and pick the largest metric
+   *   'subtitle'  | 'value' | <row index>   name it outright
+   * 'auto' is the default because it follows the card's own type scale rather
+   * than a second copy of it kept in a mapper, so a card that restyles keeps
+   * animating the right thing. A caller that disagrees names the slot instead.
+   *
+   * Measured after mount rather than guessed from props: the sizes come from
+   * tokens the consuming app can override, so only the resolved style knows.
+   */
+  let autoKey = $state<string | null>(null);
+
+  /**
+   * Re-measured whenever the card's values change, not once at mount.
+   *
+   * A card whose figures arrive from a fetch renders empty first: the balance
+   * card mounted with no balance, so the measurement found no metric, and
+   * because an attachment only re-runs when its argument changes it never looked
+   * again -- the number arrived and sat there unanimated. Keying the attachment
+   * on the values themselves fixes that, and also re-picks the primary if the
+   * card's content later changes shape.
+   */
+  const valueSignature = $derived(
+    JSON.stringify([
+      value,
+      subtitle,
+      (rows ?? []).map((row) => [
+        row.value,
+        row.comparisonValue,
+        (row.breakdown ?? []).map((item) => item.value)
+      ])
+    ])
+  );
+
+  const measurePrimary =
+    (_signature: string) =>
+    (node: HTMLElement): void => {
+      if (!animatePrimary || primary !== 'auto') {
+        return;
+      }
+      let best: string | null = null;
+      let bestSize = -1;
+      for (const slot of node.querySelectorAll('[data-sc-slot]')) {
+        if (!(slot instanceof HTMLElement)) {
+          continue;
+        }
+        if (!isAnimatableMetric(slot.textContent ?? '')) {
+          continue;
+        }
+        const size = Number.parseFloat(getComputedStyle(slot).fontSize);
+        if (Number.isFinite(size) && size > bestSize) {
+          bestSize = size;
+          best = slot.dataset.scSlot ?? null;
+        }
+      }
+      autoKey = best;
+    };
+
+  /**
+   * A numeric `primary` names a row by index, and rows carry `data-sc-slot`
+   * values of `row-<index>`. Passing the number through `String` alone yielded
+   * `'0'`, which matches no slot at all, so `primary={0}` resolved to nothing
+   * and the card animated none of its values. The custom element declares the
+   * prop as a String, so `primary="0"` arrives the same way and needs the same
+   * normalisation -- hence matching the digits rather than only `typeof`.
+   */
+  const slotKeyFor = (value: 'auto' | 'subtitle' | 'value' | number | string): string =>
+    typeof value === 'number' || /^\d+$/.test(String(value)) ? `row-${value}` : String(value);
+
+  const primaryKey = $derived(primary === 'auto' ? autoKey : slotKeyFor(primary));
+
+  /**
+   * `animateValue` keeps its old meaning -- every value on the card -- but is
+   * now gated on the value being a metric at all, so an identifier that merely
+   * contains digits is never rolled. See metric.ts: this is what stopped a store
+   * domain and a GA4 account id spinning on the anomaly cards.
+   */
+  const animates = (key: string, text: unknown): boolean => {
+    if (typeof text !== 'string' || !isAnimatableMetric(text)) {
+      return false;
+    }
+    return animatePrimary ? key === primaryKey : animateValue;
+  };
+
   /**
    * When `deltaPositive` is explicitly provided use it; otherwise infer from
    * the leading character of `delta` — '+' → positive, '-' → negative,
@@ -84,6 +181,7 @@
 
 <!-- svelte-ignore a11y_no_noninteractive_tabindex -->
 <div
+  {@attach measurePrimary(valueSignature)}
   class="statcard {classes ?? ''}"
   class:statcard-interactive={isInteractive}
   data-pw={typeof testId === 'string' ? testId : null}
@@ -189,11 +287,12 @@
               class="statcard-value"
               class:statcard-value-success={row.valueVariant === 'success'}
               class:statcard-value-warning={row.valueVariant === 'warning'}
+              data-sc-slot={`row-${rowIndex}`}
               data-pw={typeof testId === 'string' ? `${testId}-value-${rowIndex}` : null}
               testID={typeof testId === 'string' ? `${testId}-value-${rowIndex}` : null}
             >
-              {#if animateValue}
-                <AnimatedNumber value={row.value} />
+              {#if animates(`row-${rowIndex}`, row.value)}
+                <AnimatedNumber value={row.value} {animateOnMount} />
               {:else}
                 {row.value}
               {/if}
@@ -204,7 +303,8 @@
                 data-pw={typeof testId === 'string' ? `${testId}-comparison-${rowIndex}` : null}
                 testID={typeof testId === 'string' ? `${testId}-comparison-${rowIndex}` : null}
               >
-                / {#if animateValue}<AnimatedNumber
+                / {#if animates(`row-${rowIndex}-comparison`, row.comparisonValue)}<AnimatedNumber
+                    {animateOnMount}
                     value={row.comparisonValue}
                   />{:else}{row.comparisonValue}{/if}
               </div>
@@ -264,8 +364,8 @@
                   <div class="statcard-breakdown-label">{breakdownItem.label}</div>
                   <div class="statcard-breakdown-value-line">
                     <div class="statcard-breakdown-value">
-                      {#if animateValue}
-                        <AnimatedNumber value={breakdownItem.value} />
+                      {#if animates(`breakdown-${rowIndex}-${breakdownIndex}`, breakdownItem.value)}
+                        <AnimatedNumber value={breakdownItem.value} {animateOnMount} />
                       {:else}
                         {breakdownItem.value}
                       {/if}
@@ -297,11 +397,12 @@
       {:else if typeof value === 'string' && value.length > 0}
         <div
           class="statcard-value"
+          data-sc-slot="value"
           data-pw={typeof testId === 'string' ? `${testId}-value` : null}
           testID={typeof testId === 'string' ? `${testId}-value` : null}
         >
-          {#if animateValue}
-            <AnimatedNumber {value} />
+          {#if animates('value', value)}
+            <AnimatedNumber {value} {animateOnMount} />
           {:else}
             {value}
           {/if}
@@ -323,10 +424,15 @@
   {#if typeof subtitle === 'string' && subtitle.length > 0}
     <div
       class="statcard-subtitle"
+      data-sc-slot="subtitle"
       data-pw={typeof testId === 'string' ? `${testId}-subtitle` : null}
       testID={typeof testId === 'string' ? `${testId}-subtitle` : null}
     >
-      {subtitle}
+      {#if animates('subtitle', subtitle)}
+        <AnimatedNumber value={subtitle} {animateOnMount} />
+      {:else}
+        {subtitle}
+      {/if}
     </div>
   {/if}
 

package/dist/StatCard/metric.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Whether a displayed value is a METRIC worth rolling, or an identifier that
+ * merely contains digits.
+ *
+ * The distinction is not cosmetic. Adopting the odometer across a dashboard
+ * mapper animated `demo-store.myshopify.com` and `Shinchan Store GA4 (987654321)`
+ * on the anomaly surface: a store domain and a GA4 account id, rolled digit by
+ * digit as though they were measurements. Nothing was broken -- they went
+ * through the same `statcard-value` slot as `₹60k` -- which is exactly why a
+ * blanket "animate this card's values" is the wrong instruction.
+ *
+ * The rule is digits plus decoration. A metric is allowed to carry a currency
+ * symbol, a sign, a percent, group and decimal separators, and SHORT unit words
+ * -- `₹60k`, `90%`, `₹1.23Cr`, `12m 15s`, `-8%`. Anything else with a long
+ * alphabetic run, a dotted hostname or a parenthesised id is an identifier and
+ * is left alone.
+ *
+ * Deliberately conservative in one direction only: a metric wrongly refused
+ * renders exactly as it does today, while an identifier wrongly accepted is a
+ * number spinning in a domain name.
+ */
+export declare const isAnimatableMetric: (text: string) => boolean;

package/dist/StatCard/metric.js

@@ -0,0 +1,74 @@
+/**
+ * Whether a displayed value is a METRIC worth rolling, or an identifier that
+ * merely contains digits.
+ *
+ * The distinction is not cosmetic. Adopting the odometer across a dashboard
+ * mapper animated `demo-store.myshopify.com` and `Shinchan Store GA4 (987654321)`
+ * on the anomaly surface: a store domain and a GA4 account id, rolled digit by
+ * digit as though they were measurements. Nothing was broken -- they went
+ * through the same `statcard-value` slot as `₹60k` -- which is exactly why a
+ * blanket "animate this card's values" is the wrong instruction.
+ *
+ * The rule is digits plus decoration. A metric is allowed to carry a currency
+ * symbol, a sign, a percent, group and decimal separators, and SHORT unit words
+ * -- `₹60k`, `90%`, `₹1.23Cr`, `12m 15s`, `-8%`. Anything else with a long
+ * alphabetic run, a dotted hostname or a parenthesised id is an identifier and
+ * is left alone.
+ *
+ * Deliberately conservative in one direction only: a metric wrongly refused
+ * renders exactly as it does today, while an identifier wrongly accepted is a
+ * number spinning in a domain name.
+ */
+/** Unit fragments a metric may carry. Matched case-insensitively, whole-run. */
+const UNITS = new Set([
+    'k',
+    'l',
+    'm',
+    'b',
+    't',
+    'cr',
+    'lac',
+    'lakh',
+    'mn',
+    'bn',
+    's',
+    'ms',
+    'h',
+    'hr',
+    'hrs',
+    'd',
+    'day',
+    'days',
+    'min',
+    'mins',
+    'sec',
+    'secs',
+    'x',
+    'pt',
+    'pts',
+    'px'
+]);
+/** Decoration that carries no meaning for this decision. */
+const DECORATION = /[\p{Nd}\s,.:+%()[\]]|\p{Sc}|\p{Pd}|\p{Sm}/gu;
+export const isAnimatableMetric = (text) => {
+    if (typeof text !== 'string') {
+        return false;
+    }
+    const value = text.trim();
+    if (value.length === 0 || !/\p{Nd}/u.test(value)) {
+        return false;
+    }
+    // A dotted hostname or an email is an identifier however many digits it has.
+    if (/\.[a-z]{2,}(?:\/|$)|@|\/\//i.test(value)) {
+        return false;
+    }
+    // A parenthesised run of digits is an id in a label, not a measurement:
+    // "Shinchan Store GA4 (987654321)".
+    if (/\([^)]*\p{Nd}[^)]*\)/u.test(value)) {
+        return false;
+    }
+    // What remains once digits and decoration are removed must be unit words only.
+    const remainder = value.replace(DECORATION, ' ');
+    const words = remainder.split(/\s+/).filter((word) => word.length > 0);
+    return words.every((word) => UNITS.has(word.toLowerCase()));
+};

package/dist/StatCard/properties.d.ts

@@ -123,6 +123,38 @@ export type OptionalStatCardProperties = {
      * @default false
      */
     animateValue?: boolean;
+    /**
+     * Rolls the animated values up from zero as the card appears, rather than
+     * painting them outright. Requires an animation mode to be active -- either
+     * `animateValue`, or `animatePrimary` having resolved a slot to animate.
+     * Ignored when neither applies, because there is then nothing to roll.
+     *
+     * Worth turning on for a card whose figures arrive once with a fetch and then
+     * do not change, which is the ordinary dashboard case -- otherwise the
+     * odometer has nothing to react to for the life of the page.
+     * @default false
+     */
+    animateOnMount?: boolean;
+    /**
+     * Animate exactly ONE value on the card instead of all of them.
+     *
+     * Prefer this to `animateValue` on a dashboard. A card carries several numeric
+     * slots at different sizes, and animating all of them puts motion on the small
+     * supporting figures as loudly as on the headline -- which reads as noise, and
+     * on the business variant actually animated the 18px rows while the 44px
+     * subtitle above them sat still.
+     * @default false
+     */
+    animatePrimary?: boolean;
+    /**
+     * Which slot `animatePrimary` animates.
+     *
+     * `'auto'` measures the rendered slots and picks the largest one holding a
+     * metric, so the card follows its own type scale. Name a slot to override:
+     * `'subtitle'`, `'value'`, or a row index. Ignored unless `animatePrimary`.
+     * @default 'auto'
+     */
+    primary?: 'auto' | 'subtitle' | 'value' | number;
     /**
      * Multiple metric rows. When provided, replaces the single value/delta row with
      * a column of rows separated by dividers.