@juspay/svelte-ui-components 2.134.1 → 2.136.0

package/dist/TypewriterText/TypewriterText.svelte

@@ -1,12 +1,16 @@
 <script lang="ts">
   import { onMount, onDestroy, untrack } from 'svelte';
-  import type { TypewriterTextProperties } from './properties';
+  import type { TypewriterTextProperties, TypewriterCharacterDelayRange } from './properties';
 
   let {
     text,
     speed = 15,
     isStreaming = false,
     renderText,
+    variableDelay,
+    resolveDelay,
+    onProgress,
+    renderCharacter,
     testId,
     classes
   }: TypewriterTextProperties = $props();
@@ -18,11 +22,63 @@
   // Where typing left off, so newly streamed-in text continues rather than restarts.
   let previousTextLength = $state(0);
 
+  // Whitespace characters revealed so far — the state `resolveDelay` reads via
+  // `TypewriterDelayContext.wordCount`. Reset alongside the other typing state
+  // whenever `text` is replaced rather than continued (see the mount $effect below).
+  let revealedWordCount = $state(0);
+
+  const WHITESPACE_CHARACTERS = new Set([' ', '\n']);
+  const PUNCTUATION_CHARACTERS = new Set([',', '.', '?', '!']);
+  const DIGIT_PATTERN = /\d/;
+
+  const randomDelayInRange = (range: TypewriterCharacterDelayRange): number => {
+    return range.min + Math.random() * (range.max - range.min);
+  };
+
+  // Falls straight through to the flat `speed` — byte-identical to the pre-`variableDelay`
+  // behaviour — for any consumer that never sets `variableDelay`/`resolveDelay`, or leaves
+  // a class out of `variableDelay`. `resolveDelay`, when set, takes over entirely: it is
+  // the more general mechanism (see its doc comment in properties.ts) and is expected to
+  // own the full pacing decision rather than compose with `variableDelay`/`speed`.
+  const resolveTypingDelay = (character: string, characterIndex: number): number => {
+    if (typeof resolveDelay === 'function') {
+      return resolveDelay({ character, index: characterIndex, wordCount: revealedWordCount });
+    }
+    if (!variableDelay) {
+      return speed;
+    }
+    if (DIGIT_PATTERN.test(character) && variableDelay.digit) {
+      return randomDelayInRange(variableDelay.digit);
+    }
+    if (WHITESPACE_CHARACTERS.has(character) && variableDelay.whitespace) {
+      return randomDelayInRange(variableDelay.whitespace);
+    }
+    if (PUNCTUATION_CHARACTERS.has(character) && variableDelay.punctuation) {
+      return randomDelayInRange(variableDelay.punctuation);
+    }
+    if (variableDelay.default) {
+      return randomDelayInRange(variableDelay.default);
+    }
+    return speed;
+  };
+
   const typeNextCharacter = (): void => {
     if (currentIndex < text.length) {
+      const revealedCharacter = text[currentIndex];
+      const revealedCharacterIndex = currentIndex;
+      // Word count is updated for THIS character before it is used to resolve THIS
+      // character's own delay — the ordering `TypewriterDelayContext.wordCount` documents
+      // and that a cyclical/positional `resolveDelay` depends on.
+      if (WHITESPACE_CHARACTERS.has(revealedCharacter)) {
+        revealedWordCount++;
+      }
       displayedText = text.substring(0, currentIndex + 1);
       currentIndex++;
-      timeoutId = setTimeout(typeNextCharacter, speed);
+      onProgress?.({ index: currentIndex, total: text.length, displayedText });
+      timeoutId = setTimeout(
+        typeNextCharacter,
+        resolveTypingDelay(revealedCharacter, revealedCharacterIndex)
+      );
     }
   };
 
@@ -47,6 +103,7 @@
         displayedText = '';
         currentIndex = 0;
         previousTextLength = 0;
+        revealedWordCount = 0;
       }
       if (nextText.length > 0 && nextText.length > previousTextLength) {
         if (currentIndex >= previousTextLength) {
@@ -66,8 +123,12 @@
       if (timeoutId !== null) {
         clearTimeout(timeoutId);
       }
+      const hadRemainingText = currentIndex < text.length;
       displayedText = text;
       currentIndex = text.length;
+      if (hadRemainingText) {
+        onProgress?.({ index: currentIndex, total: text.length, displayedText });
+      }
     }
   });
 
@@ -94,6 +155,10 @@
   {#if typeof renderText === 'function'}
     <!-- eslint-disable-next-line svelte/no-at-html-tags -->
     {@html renderText(displayedText)}
+  {:else if renderCharacter}
+    {#each displayedText.split('') as character, index (index)}
+      {@render renderCharacter({ character, index })}
+    {/each}
   {:else}
     {displayedText}
   {/if}

package/dist/TypewriterText/properties.d.ts

@@ -1,9 +1,72 @@
+import type { Snippet } from 'svelte';
 export type TypewriterTextProperties = OptionalTypewriterTextProperties & MandatoryTypewriterTextProperties;
 export type MandatoryTypewriterTextProperties = {
     text: string;
 };
+/** A random delay in `[min, max]` milliseconds is picked per character in that class. Pass equal `min`/`max` for a fixed delay. */
+export type TypewriterCharacterDelayRange = {
+    min: number;
+    max: number;
+};
+/**
+ * Per-character-class pacing, in place of the flat `speed`. Reach for this when a
+ * conversation needs to slow down for numbers (prices, OTPs, phone numbers) or add a
+ * beat at punctuation, the way a person reading it aloud would. Any class you omit —
+ * including `default` — falls back to `speed` for that character.
+ */
+export type TypewriterVariableDelay = {
+    /** Digits (`0`–`9`). */
+    digit?: TypewriterCharacterDelayRange;
+    /** A space or newline — the natural word-boundary pause. */
+    whitespace?: TypewriterCharacterDelayRange;
+    /** Sentence punctuation: `,` `.` `?` `!`. */
+    punctuation?: TypewriterCharacterDelayRange;
+    /** Every other character (letters and anything not covered above). */
+    default?: TypewriterCharacterDelayRange;
+};
+export type TypewriterProgress = {
+    /** Characters revealed so far. */
+    index: number;
+    /** Length of `text` at the time of this update — compare against `index` for a percentage. */
+    total: number;
+    /** The text revealed so far — the same value driving what's on screen. */
+    displayedText: string;
+};
+export type TypewriterCharacterContext = {
+    /** The character being rendered. */
+    character: string;
+    /** Its position within the full `text` string. */
+    index: number;
+};
+/**
+ * Everything `resolveDelay` gets to decide the next character's pacing from — a
+ * superset of `TypewriterCharacterContext` because pacing can depend on more than the
+ * character alone (see `wordCount`).
+ */
+export type TypewriterDelayContext = TypewriterCharacterContext & {
+    /**
+     * Whitespace characters (space or newline) revealed so far — INCLUDING this one, if
+     * `character` itself is whitespace. The component always updates this count before
+     * calling `resolveDelay`, so a cadence that keys off word position (a cyclical
+     * acceleration window, slowing down only for the first word of a sentence, etc.) can
+     * rely on that ordering instead of inferring it through a side channel like
+     * `onProgress`. Counts only whitespace, matching the `whitespace` class in
+     * `TypewriterVariableDelay` — it is not a word index in any richer sense.
+     */
+    wordCount: number;
+};
+/**
+ * Computes the delay before the NEXT character types, given the one that was just
+ * revealed and enough state (`index`, `wordCount`) to vary that delay with position —
+ * not just character class. Reach for this instead of `variableDelay` when the cadence
+ * needs to depend on where typing currently is, not only on what the character is: e.g.
+ * an accelerating window every N words, or a pause that only applies to the first
+ * occurrence of a character class. `variableDelay` stays the right tool for a pure
+ * per-class rule with no positional state.
+ */
+export type TypewriterDelayResolver = (context: TypewriterDelayContext) => number;
 export type OptionalTypewriterTextProperties = {
-    /** Milliseconds between characters. */
+    /** Milliseconds between characters. Ignored per character class covered by `variableDelay`. */
     speed?: number;
     /**
      * While `true`, text revealed so far stays and new text keeps typing as `text` grows.
@@ -16,6 +79,39 @@ export type OptionalTypewriterTextProperties = {
      * text can contain untrusted input. When omitted, the text renders as plain text.
      */
     renderText?: (text: string) => string;
+    /**
+     * Opt into per-character-class pacing (digits, whitespace, punctuation, everything
+     * else) instead of the flat `speed`. Omit to keep the flat `speed` for every character.
+     */
+    variableDelay?: TypewriterVariableDelay;
+    /**
+     * Opt into a fully custom pacing function, called once per character in place of
+     * `variableDelay`/`speed`. Needed when the cadence isn't a pure function of the
+     * character's own class — e.g. an accelerating window that recurs every N words and,
+     * while active, collapses whitespace/punctuation/default pacing to a single flat
+     * range regardless of class, with only digits kept slow throughout. `variableDelay`
+     * cannot express that fourth, position-driven case because it re-evaluates from
+     * scratch per character with no notion of where typing currently is; `resolveDelay`
+     * closes that gap by handing the resolver `index` and `wordCount` alongside the
+     * character (see `TypewriterDelayContext` for the ordering guarantee on `wordCount`),
+     * so state like a running cycle position can live in the resolver's own closure
+     * instead of a side channel like swapping `variableDelay` from inside `onProgress`.
+     * Takes priority over `variableDelay` when both are set. Omit to keep
+     * `variableDelay`/`speed` resolution exactly as today.
+     */
+    resolveDelay?: TypewriterDelayResolver;
+    /**
+     * Called every time a character is revealed (and once more if `isStreaming` turns
+     * `false` while text remains, since the rest appears at once) — scroll a container to
+     * follow the reveal, or show how far along it is. Not called when omitted.
+     */
+    onProgress?: (progress: TypewriterProgress) => void;
+    /**
+     * Render each revealed character yourself — highlight a token, wrap a number — instead
+     * of the plain text node. Ignored when `renderText` is set, since that renderer already
+     * owns the full markup. Falls back to plain text per character when omitted.
+     */
+    renderCharacter?: Snippet<[TypewriterCharacterContext]>;
     testId?: string;
     classes?: string;
 };

package/dist/index.d.ts

@@ -120,6 +120,7 @@ export type * from './Table/properties';
 export type { NormalizedColumns } from './Table/normalizeColumns';
 export type { SortTableRowsOptions, TableSortType } from './Table/sortEngine';
 export type * from './Stepper/properties';
+export type { Step as StepperStep } from './Stepper/properties';
 export type * from './Toast/properties';
 export type * from './IconStack/properties';
 export type * from './Img/properties';
@@ -197,5 +198,5 @@ export type * from './MediaPlayer/properties';
 export type * from './MediaUpload/properties';
 export type * from './Gallery/properties';
 export { createSoundKit } from './soundKit/soundKit';
-export { validateInput } from './utils';
+export { validateInput, lockBodyScroll, unlockBodyScroll } from './utils';
 export { formatNumberIndian } from './_chart/format';

package/dist/index.js

@@ -101,5 +101,5 @@ export { ChatController } from './Chat/controller.svelte';
 export { partyOf } from './Chat/roles';
 export { SpeechToTextController } from './SpeechToText/controller.svelte';
 export { createSoundKit } from './soundKit/soundKit';
-export { validateInput } from './utils';
+export { validateInput, lockBodyScroll, unlockBodyScroll } from './utils';
 export { formatNumberIndian } from './_chart/format';

package/dist/utils.d.ts

@@ -26,3 +26,5 @@ export declare function hslToHsv(hDeg: number, sPct: number, lPct: number): Hsv;
 export declare function isValidHex(hex: string): boolean;
 export declare function clampInt(v: string, min: number, max: number): number;
 export declare function createDebouncer(delay: number): <T extends unknown[]>(callback: (...args: T) => void, ...args: T) => void;
+export declare function lockBodyScroll(): void;
+export declare function unlockBodyScroll(): void;

package/dist/utils.js

@@ -292,3 +292,33 @@ export function createDebouncer(delay) {
         }
     };
 }
+/**
+ * Body scroll lock, reference counted.
+ *
+ * Modal, Sheet and CommandMenu each hide body overflow while they are open. Doing
+ * that with a bare assignment means the FIRST of them to unmount restores
+ * scrolling for all of them, so closing a confirmation dialog inside a still-open
+ * modal silently lets the page behind it scroll again. Counting the holders keeps
+ * the lock until the last one releases it.
+ *
+ * Callers must pair every lock with exactly one unlock.
+ */
+let bodyScrollLockCount = 0;
+export function lockBodyScroll() {
+    if (typeof document === 'undefined') {
+        return;
+    }
+    if (bodyScrollLockCount === 0) {
+        document.body.style.overflow = 'hidden';
+    }
+    bodyScrollLockCount += 1;
+}
+export function unlockBodyScroll() {
+    if (typeof document === 'undefined') {
+        return;
+    }
+    bodyScrollLockCount = Math.max(0, bodyScrollLockCount - 1);
+    if (bodyScrollLockCount === 0) {
+        document.body.style.overflow = '';
+    }
+}