@juspay/svelte-ui-components 4.29.0 → 4.30.0

package/dist/DateRangePicker/DateRangePicker.svelte

@@ -11,6 +11,7 @@
   import { focusTrapTabTarget, getFocusTrapBoundary } from '../_interaction/focus';
   import { getActiveElement } from '../_interaction/focus';
   import { registerDismissible } from '../_interaction/dismissal';
+  import { describeField } from '../_field/description';
   import chevronDownSvg from '../assets/chevron-down.svg?raw';
   import checkmarkSvg from '../assets/checkmark.svg?raw';
   import chevronRightSvg from '../assets/chevron-right.svg?raw';
@@ -679,12 +680,20 @@
      The two layout branches below (`isInlineTime` and its `{:else}`) are
      mutually exclusive, so the same four ids are never in the document twice. */
   const drpFieldUid = $props.id();
-  const startDateErrorId = `${drpFieldUid}-start-date-error`;
-  const startTimeErrorId = `${drpFieldUid}-start-time-error`;
-  const endDateErrorId = `${drpFieldUid}-end-date-error`;
-  const endTimeErrorId = `${drpFieldUid}-end-time-error`;
   const DATE_HINT = 'Enter a date this picker accepts, like 12 Mar 2025.';
   const TIME_HINT = 'Enter a time like 12:00 AM.';
+  const startDateField = $derived(
+    describeField(`${drpFieldUid}-start-date`, { error: isStartDateValid ? null : DATE_HINT })
+  );
+  const startTimeField = $derived(
+    describeField(`${drpFieldUid}-start-time`, { error: isStartTimeValid ? null : TIME_HINT })
+  );
+  const endDateField = $derived(
+    describeField(`${drpFieldUid}-end-date`, { error: isEndDateValid ? null : DATE_HINT })
+  );
+  const endTimeField = $derived(
+    describeField(`${drpFieldUid}-end-time`, { error: isEndTimeValid ? null : TIME_HINT })
+  );
 
   // True when date's month is already one of the two visible calendar months (or the
   // single visible month outside dual-month mode) — used to avoid an unnecessary
@@ -1038,7 +1047,7 @@
                         placeholder="Start date"
                         aria-label="Start date"
                         aria-invalid={!isStartDateValid}
-                        aria-describedby={isStartDateValid ? null : startDateErrorId}
+                        aria-describedby={startDateField.describedBy}
                         onblur={() => commitTypedDate('start')}
                         onkeydown={(event) => handleDateInputKeyDown(event, 'start')}
                         data-pw={testId ? `${testId}-start-date` : null}
@@ -1059,14 +1068,22 @@
                         placeholder="12:00 AM"
                         aria-label="Start time"
                         aria-invalid={!isStartTimeValid}
-                        aria-describedby={isStartTimeValid ? null : startTimeErrorId}
+                        aria-describedby={startTimeField.describedBy}
                         data-pw={testId ? `${testId}-start-time` : null}
                         testID={testId ? `${testId}-start-time` : null}
                       />
                     </div>
-                    {@render drpFieldError(startDateErrorId, !isStartDateValid, DATE_HINT)}
+                    {@render drpFieldError(
+                      startDateField.errorId,
+                      startDateField.showsError,
+                      DATE_HINT
+                    )}
                   </div>
-                  {@render drpFieldError(startTimeErrorId, !isStartTimeValid, TIME_HINT)}
+                  {@render drpFieldError(
+                    startTimeField.errorId,
+                    startTimeField.showsError,
+                    TIME_HINT
+                  )}
                   <!-- eslint-disable-next-line svelte/no-at-html-tags -->
                   <span class="drp-datetime-arrow" aria-hidden="true">{@html chevronRightSvg}</span>
                   <div class="drp-date-time-group">
@@ -1080,7 +1097,7 @@
                         placeholder="End date"
                         aria-label="End date"
                         aria-invalid={!isEndDateValid}
-                        aria-describedby={isEndDateValid ? null : endDateErrorId}
+                        aria-describedby={endDateField.describedBy}
                         onblur={() => commitTypedDate('end')}
                         onkeydown={(event) => handleDateInputKeyDown(event, 'end')}
                         data-pw={testId ? `${testId}-end-date` : null}
@@ -1101,14 +1118,18 @@
                         placeholder="11:59 PM"
                         aria-label="End time"
                         aria-invalid={!isEndTimeValid}
-                        aria-describedby={isEndTimeValid ? null : endTimeErrorId}
+                        aria-describedby={endTimeField.describedBy}
                         data-pw={testId ? `${testId}-end-time` : null}
                         testID={testId ? `${testId}-end-time` : null}
                       />
                     </div>
-                    {@render drpFieldError(endDateErrorId, !isEndDateValid, DATE_HINT)}
+                    {@render drpFieldError(
+                      endDateField.errorId,
+                      endDateField.showsError,
+                      DATE_HINT
+                    )}
                   </div>
-                  {@render drpFieldError(endTimeErrorId, !isEndTimeValid, TIME_HINT)}
+                  {@render drpFieldError(endTimeField.errorId, endTimeField.showsError, TIME_HINT)}
                 {:else}
                   <div class="drp-date-input" class:drp-date-input-invalid={!isStartDateValid}>
                     <input
@@ -1120,13 +1141,17 @@
                       placeholder="Start date"
                       aria-label="Start date"
                       aria-invalid={!isStartDateValid}
-                      aria-describedby={isStartDateValid ? null : startDateErrorId}
+                      aria-describedby={startDateField.describedBy}
                       onblur={() => commitTypedDate('start')}
                       onkeydown={(event) => handleDateInputKeyDown(event, 'start')}
                       data-pw={testId ? `${testId}-start-date` : null}
                       testID={testId ? `${testId}-start-date` : null}
                     />
-                    {@render drpFieldError(startDateErrorId, !isStartDateValid, DATE_HINT)}
+                    {@render drpFieldError(
+                      startDateField.errorId,
+                      startDateField.showsError,
+                      DATE_HINT
+                    )}
                   </div>
                   <!-- eslint-disable-next-line svelte/no-at-html-tags -->
                   <span class="drp-datetime-arrow" aria-hidden="true">{@html chevronRightSvg}</span>
@@ -1140,13 +1165,17 @@
                       placeholder="End date"
                       aria-label="End date"
                       aria-invalid={!isEndDateValid}
-                      aria-describedby={isEndDateValid ? null : endDateErrorId}
+                      aria-describedby={endDateField.describedBy}
                       onblur={() => commitTypedDate('end')}
                       onkeydown={(event) => handleDateInputKeyDown(event, 'end')}
                       data-pw={testId ? `${testId}-end-date` : null}
                       testID={testId ? `${testId}-end-date` : null}
                     />
-                    {@render drpFieldError(endDateErrorId, !isEndDateValid, DATE_HINT)}
+                    {@render drpFieldError(
+                      endDateField.errorId,
+                      endDateField.showsError,
+                      DATE_HINT
+                    )}
                   </div>
                   {#if showTimeSelection}
                     <button
@@ -1178,11 +1207,15 @@
                       placeholder="12:00 AM"
                       aria-label="Start time"
                       aria-invalid={!isStartTimeValid}
-                      aria-describedby={isStartTimeValid ? null : startTimeErrorId}
+                      aria-describedby={startTimeField.describedBy}
                       data-pw={testId ? `${testId}-start-time` : null}
                       testID={testId ? `${testId}-start-time` : null}
                     />
-                    {@render drpFieldError(startTimeErrorId, !isStartTimeValid, TIME_HINT)}
+                    {@render drpFieldError(
+                      startTimeField.errorId,
+                      startTimeField.showsError,
+                      TIME_HINT
+                    )}
                   </div>
                   <!-- eslint-disable-next-line svelte/no-at-html-tags -->
                   <span class="drp-datetime-arrow" aria-hidden="true">{@html chevronRightSvg}</span>
@@ -1197,11 +1230,15 @@
                       placeholder="11:59 PM"
                       aria-label="End time"
                       aria-invalid={!isEndTimeValid}
-                      aria-describedby={isEndTimeValid ? null : endTimeErrorId}
+                      aria-describedby={endTimeField.describedBy}
                       data-pw={testId ? `${testId}-end-time` : null}
                       testID={testId ? `${testId}-end-time` : null}
                     />
-                    {@render drpFieldError(endTimeErrorId, !isEndTimeValid, TIME_HINT)}
+                    {@render drpFieldError(
+                      endTimeField.errorId,
+                      endTimeField.showsError,
+                      TIME_HINT
+                    )}
                   </div>
                 </div>
               {/if}
@@ -1612,6 +1649,18 @@
     border-color: var(--drp-date-input-invalid-border, #e5484d);
   }
 
+  /* .drp-date-input-value below sets outline: none with nothing standing in
+     for it, so the visible replacement lives on the bordered wrapper instead
+     -- :focus-within lights up whenever the text input inside is focused.
+     class:drp-date-input-invalid sits alongside .drp-date-input on the same
+     div (see markup), and :focus-within's extra pseudo-class outweighs that
+     single class, so a focused invalid field shows the focus border, not the
+     invalid one -- focus location is the more time-sensitive signal. */
+  .drp-date-input:focus-within {
+    border-color: var(--drp-date-input-focus-border, #2563eb);
+    box-shadow: var(--drp-date-input-focus-shadow, 0 0 0 2px rgba(37, 99, 235, 0.2));
+  }
+
   .drp-date-input-value {
     display: block;
     width: 100%;
@@ -1691,6 +1740,14 @@
     border-color: var(--drp-time-input-invalid-border, #e5484d);
   }
 
+  /* .drp-time-field below sets outline: none with nothing standing in for it;
+     same fix as .drp-date-input:focus-within above, same specificity
+     reasoning against .drp-time-input-invalid. */
+  .drp-time-input:focus-within {
+    border-color: var(--drp-time-input-focus-border, #2563eb);
+    box-shadow: var(--drp-time-input-focus-shadow, 0 0 0 2px rgba(37, 99, 235, 0.2));
+  }
+
   .drp-time-input-icon {
     display: inline-flex;
     flex-shrink: 0;

package/dist/DeltaIndicator/DeltaIndicator.svelte

@@ -1,4 +1,5 @@
 <script lang="ts">
+  import AnimatedNumber from '../AnimatedNumber/AnimatedNumber.svelte';
   import type { DeltaIndicatorProperties, DeltaDirection } from './properties';
 
   let {
@@ -7,6 +8,7 @@
     invertColors = false,
     hideArrow = false,
     neutralThreshold = 0,
+    animateValue = false,
     testId,
     classes
   }: DeltaIndicatorProperties = $props();
@@ -50,7 +52,16 @@
          place of the trend arrow, so a flat delta still reads as a stated state. -->
     <span class="delta-indicator-dash" aria-hidden="true">—</span>
   {/if}
-  <span class="delta-indicator-text">{text}</span>
+  <span class="delta-indicator-text">
+    {#if animateValue}
+      <!-- The formatter's STRING output, not `value` -- a consumer's own `format`
+           must still animate, and this component has no business re-deriving or
+           second-guessing what that formatter produced. -->
+      <AnimatedNumber value={text} />
+    {:else}
+      {text}
+    {/if}
+  </span>
 </span>
 
 <style>

package/dist/DeltaIndicator/properties.d.ts

@@ -19,6 +19,15 @@ export type OptionalDeltaIndicatorProperties = {
     hideArrow?: boolean;
     /** Absolute values at or below this are treated as `neutral` (default 0). */
     neutralThreshold?: number;
+    /**
+     * Roll the displayed text through `AnimatedNumber` instead of setting it as
+     * plain text on every `value`/`format` change. The formatter's OUTPUT
+     * STRING is what gets passed through, not the raw `value` -- so a custom
+     * `format` still animates without this component having to guess at, or
+     * reproduce, its formatting.
+     * @default false
+     */
+    animateValue?: boolean;
     /** Test selector applied as the `data-pw` attribute. */
     testId?: string | null;
     /** Additional CSS classes for theming. */

package/dist/Gallery/Gallery.svelte

@@ -533,6 +533,22 @@
     outline: none;
   }
 
+  /* lightboxAction focuses this element directly on open (and goToIndex
+     re-focuses it whenever focus isn't already inside), and it's the
+     Tab-trap's own boundary, so the unconditional :focus suppression above
+     left a keyboard user with no visible sign focus had moved into the
+     lightbox at all. :focus-visible wins the cascade over the plain :focus
+     rule above (equal specificity, later in source, and a strict subset) only
+     when the browser judges this came from keyboard/programmatic focus, so
+     the thumbnail click that opens the lightbox still shows nothing new.
+     outline-offset is negative (inset), matching Sheet's sheet-panel: the
+     lightbox sits flush against all four viewport edges, so a positive offset
+     would clip. */
+  .lightbox:focus-visible {
+    outline: var(--gallery-lightbox-focus-outline, 2px solid #2563eb);
+    outline-offset: var(--gallery-lightbox-focus-outline-offset, -2px);
+  }
+
   .lightbox-figure {
     display: flex;
     flex-direction: column;

package/dist/Gauge/Gauge.svelte

@@ -1,4 +1,5 @@
 <script lang="ts">
+  import AnimatedNumber from '../AnimatedNumber/AnimatedNumber.svelte';
   import type { GaugeProperties } from './properties';
 
   let {
@@ -6,6 +7,7 @@
     max = 100,
     showLabel = true,
     labelFormatter,
+    animateValue = false,
     ariaLabel,
     testId,
     classes
@@ -24,7 +26,8 @@
   // labelFormatter receives the raw (value, max) pair so callers have full
   // context. The built-in fallback shows the computed percentage string
   // (e.g. value=50, max=200 → "25%").
-  let labelText = $derived(labelFormatter ? labelFormatter(value, max) : `${Math.round(clamped)}%`);
+  let roundedPercentage = $derived(Math.round(clamped));
+  let labelText = $derived(labelFormatter ? labelFormatter(value, max) : `${roundedPercentage}%`);
 </script>
 
 <div
@@ -52,7 +55,23 @@
     />
   </svg>
   {#if showLabel}
-    <div class="label">{labelText}</div>
+    <div class="label">
+      {#if animateValue}
+        {#if labelFormatter}
+          <AnimatedNumber value={labelText} />
+        {:else}
+          <!-- The unit goes INSIDE AnimatedNumber, not beside it. The odometer
+             carries role="img" with its own aria-label, so a unit left outside is
+             invisible to anyone navigating by graphic -- the rotor reads "75" with
+             no sign of what it measures. Passing the formatted string keeps the
+             unit in the accessible name; only the digits move, since the string
+             path rolls the characters that changed and leaves the rest. -->
+          <AnimatedNumber value={`${roundedPercentage}%`} />
+        {/if}
+      {:else}
+        {labelText}
+      {/if}
+    </div>
   {/if}
 </div>
 

package/dist/Gauge/properties.d.ts

@@ -19,6 +19,19 @@ export type OptionalGaugeProperties = {
      * Example: `labelFormatter={(v, m) => \`${v} / ${m}\`}` shows "50 / 200".
      */
     labelFormatter?: (value: number, max: number) => string;
+    /**
+     * Routes the centered label through `AnimatedNumber` so it rolls to its new
+     * value instead of jumping. Both routes pass a complete STRING and diff it
+     * character by character: `labelFormatter`'s own output when it is set, and
+     * `` `${roundedPercentage}%` `` when it is not. The unit goes inside rather
+     * than beside, because the odometer carries `role="img"` with its own
+     * accessible name and anything left outside is invisible to a reader
+     * navigating by graphic. Only the digits move; the `%` is a literal column
+     * that never rolls. Off by default so an unset prop renders the exact static
+     * text node it always has.
+     * @default false
+     */
+    animateValue?: boolean;
     /**
      * Accessible label for the gauge element (`role="progressbar"`). Falls back
      * to the computed `labelText` (e.g. `"75%"`) when not provided, so assistive

package/dist/Input/Input.svelte

@@ -1,6 +1,7 @@
 <script lang="ts">
   import { prefersReducedMotion } from '../utils';
   import { getActiveElement } from '../_interaction/focus';
+  import { describeField } from '../_field/description';
   import { validateInput } from '../utils';
   import type { InputProperties } from './properties';
   import type { ValidationState } from '../types';
@@ -137,25 +138,23 @@
   // forceError lets consumers drive the error border from server/runtime validation,
   // independent of validationPattern.
   const showError = $derived(showErrorMessage || forceError);
-  // The error text has to be reachable FROM the field it describes and announced when it
-  // appears. Without both, a screen-reader user submits, hears nothing, and is left on a form
-  // that did not move -- the message is on screen and absent from the accessibility tree.
-  const errorMessageId = $derived(`${effectiveId}-error`);
+  // `actionInput` renders no error/info UI at all, so it gates the whole field
+  // description off rather than being threaded through describeField itself.
+  const effectiveShowError = $derived(showError && !actionInput);
   // `onErrorMessage` is `string | null`, so null has to be excluded explicitly: `null !== ''`
   // is true, which would describe the field by an alert element carrying no message.
-  const isShowingError = $derived(
-    onErrorMessage != null && onErrorMessage !== '' && showError && !actionInput
-  );
-  const infoMessageId = $derived(`${effectiveId}-info`);
-  const isShowingInfo = $derived(infoMessage !== '' && !actionInput);
-  // Helper text is part of the field's description, not decoration: a consumer's `infoMessage`
-  // ("Enter a percentage between 1 and 100") is exactly the guidance a screen-reader user needs
-  // BEFORE they trip an error. Reference both, in reading order, so the field is described by
-  // everything visibly attached to it rather than only by its failure.
-  const describedBy = $derived(
-    [isShowingError ? errorMessageId : null, isShowingInfo ? infoMessageId : null]
-      .filter(Boolean)
-      .join(' ')
+  // forceError with no message still has to mark the field invalid -- describeField's
+  // `invalid` override exists for exactly that -- but it cannot be described by an
+  // element that will not be rendered, so only a real message is passed as `error`.
+  const field = $derived(
+    describeField(effectiveId, {
+      error:
+        effectiveShowError && onErrorMessage != null && onErrorMessage !== ''
+          ? onErrorMessage
+          : null,
+      info: !actionInput && infoMessage !== '' ? infoMessage : null,
+      invalid: effectiveShowError
+    })
   );
   const hasLeftIcon = $derived(typeof leftIcon === 'function');
   const hasRightIcon = $derived(typeof rightIcon === 'function');
@@ -336,8 +335,8 @@
         aria-controls={ariaControls}
         aria-activedescendant={ariaActivedescendant}
         aria-required={isRequired || null}
-        aria-invalid={showError && !actionInput ? 'true' : null}
-        aria-describedby={describedBy || null}
+        aria-invalid={field.ariaInvalid}
+        aria-describedby={field.describedBy}
         required={isRequired || null}
         {onfocus}
         onfocusout={_onFocusOut}
@@ -374,8 +373,8 @@
         aria-controls={ariaControls}
         aria-activedescendant={ariaActivedescendant}
         aria-required={isRequired || null}
-        aria-invalid={showError && !actionInput ? 'true' : null}
-        aria-describedby={describedBy || null}
+        aria-invalid={field.ariaInvalid}
+        aria-describedby={field.describedBy}
         required={isRequired || null}
         {onfocus}
         onfocusout={_onFocusOut}
@@ -438,9 +437,9 @@
     {@render fieldElement()}
   {/if}
 
-  {#if isShowingError}
+  {#if field.showsError}
     <div
-      id={errorMessageId}
+      id={field.errorId}
       role="alert"
       class="error-message"
       data-pw={typeof testId === 'string' && testId.length > 0 ? `${testId}-error-message` : null}
@@ -449,9 +448,9 @@
       {onErrorMessage}
     </div>
   {/if}
-  {#if isShowingInfo}
+  {#if field.showsInfo}
     <div
-      id={infoMessageId}
+      id={field.infoId}
       class="info-message"
       data-pw={typeof testId === 'string' && testId.length > 0 ? `${testId}-info-message` : null}
       testID={typeof testId === 'string' && testId.length > 0 ? `${testId}-info-message` : null}
@@ -504,9 +503,18 @@
     color: var(--input-text-color, #333333);
   }
 
+  /* The fallback used to be `1px solid transparent` -- a border that changes
+     width/style but not colour, so a mouse-focused OR keyboard-focused field
+     looked identical to unfocused. Text inputs use a real :focus (not
+     :focus-visible): unlike a button-shaped control, a text field's focus
+     ring has to stay visible regardless of input modality, since a mouse
+     click into a field is itself the start of a keyboard interaction.
+     --input-focus-border-color already exists for exactly this colour (see
+     .input-icon-button:focus-visible below), so this reuses it instead of
+     minting a second token for the same ring. */
   textarea:focus,
   input:focus {
-    border: var(--input-focus-border, 1px solid transparent);
+    border: var(--input-focus-border, 1px solid var(--input-focus-border-color, #005fcc));
   }
 
   .input-error {

package/dist/KeyboardInput/KeyboardInput.svelte

@@ -79,7 +79,7 @@
   }
 
   .separator {
-    color: var(--keyboard-input-separator-color, #888888);
+    color: var(--keyboard-input-separator-color, #6b7280);
     font-size: var(--keyboard-input-separator-font-size, 0.85em);
     user-select: none;
   }

package/dist/ListItem/ListItem.svelte

@@ -3,12 +3,14 @@
   import Loader from '../Loader/Loader.svelte';
   import Img from '../Img/Img.svelte';
   import type { ListItemProperties } from './properties';
+  import { resolveLabelHtml } from './label';
 
   let {
     leftImageUrl,
     leftImageFallbackUrl,
     rightImageUrl,
     label,
+    sanitize,
     useAccordion = false,
     rightContentText,
     testId,
@@ -60,6 +62,11 @@
   );
   let itemInteractive = $derived(!suppressRoleAndTabindex && itemRole !== 'option');
 
+  // Escaped plain text by default; markup only through a consumer-supplied
+  // sanitizer -- see ListItemSanitizeOptions in properties.ts and
+  // docs/ListItem.md "Rendering markup in the label" for the full contract.
+  let labelHtml = $derived(typeof label === 'string' ? resolveLabelHtml(label, sanitize) : '');
+
   function handleLeftImageClick(event: MouseEvent): void {
     onleftimageclick?.(event);
   }
@@ -182,8 +189,11 @@
               data-pw={centerTextTestId}
               testID={centerTextTestId}
             >
-              <!-- eslint-disable-next-line -->
-              {@html label}
+              <!-- labelHtml is escaped by default; markup only reaches here through a
+                   consumer-supplied sanitizer -- see ListItemSanitizeOptions.htmlSanitizer
+                   in properties.ts. -->
+              <!-- eslint-disable-next-line svelte/no-at-html-tags -->
+              {@html labelHtml}
             </div>
           {/if}
           {#if typeof centerContent === 'function'}
@@ -404,6 +414,21 @@
   .prevent-focus:focus {
     outline: none;
   }
+
+  /* preventFocus does not touch tabindex (see the root's tabindex expression
+     above -- itemRole/suppressRoleAndTabindex govern that, unconditional on
+     this prop), so every element carrying .prevent-focus stays a real,
+     keyboard-Tab-reachable stop by default. docs/ListItem.md documents the
+     prop as removing the outline "for non-keyboard navigation contexts" --
+     :focus-visible is that exact distinction already built into the
+     platform: it does not match a mouse/touch-triggered focus (the case the
+     prop exists for) but does match a real keyboard Tab, so this restores
+     WCAG 2.4.7 visibility for the one case preventFocus was never meant to
+     hide it from. */
+  .prevent-focus:focus-visible {
+    outline: var(--list-item-focus-outline, 2px solid #2563eb);
+    outline-offset: var(--list-item-focus-outline-offset, -2px);
+  }
   /* The loader is not the only motion in this file, and this block sits at the
      END on purpose: `.item` is declared after the guard above, so an override
      placed there would lose the same-specificity tie on source order -- the

package/dist/ListItem/label.d.ts

@@ -0,0 +1,11 @@
+import type { ListItemSanitizeOptions } from './properties';
+/**
+ * Resolves what ListItem's `label` renders as through `{@html}`.
+ *
+ * Defaults to escaped plain text. `sanitize.rawHtml: 'sanitize'` with a
+ * `sanitize.htmlSanitizer` supplied renders `label` as markup instead, through
+ * that sanitizer — see `ListItemSanitizeOptions.htmlSanitizer` for the full
+ * contract (called once, falls back to escaping on throw or a non-string
+ * return, `'sanitize'` with no sanitizer supplied is exactly `'escape'`).
+ */
+export declare function resolveLabelHtml(label: string, sanitize?: ListItemSanitizeOptions): string;

package/dist/ListItem/label.js

@@ -0,0 +1,40 @@
+function escapeHtml(value) {
+    return value
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+/**
+ * A consumer's sanitizer is arbitrary code. `null` here means it did not
+ * return usable markup, and the caller falls back to escaping — never to
+ * the unsanitized string.
+ */
+function runSanitizer(html, htmlSanitizer) {
+    try {
+        const sanitized = htmlSanitizer(html);
+        return typeof sanitized === 'string' ? sanitized : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolves what ListItem's `label` renders as through `{@html}`.
+ *
+ * Defaults to escaped plain text. `sanitize.rawHtml: 'sanitize'` with a
+ * `sanitize.htmlSanitizer` supplied renders `label` as markup instead, through
+ * that sanitizer — see `ListItemSanitizeOptions.htmlSanitizer` for the full
+ * contract (called once, falls back to escaping on throw or a non-string
+ * return, `'sanitize'` with no sanitizer supplied is exactly `'escape'`).
+ */
+export function resolveLabelHtml(label, sanitize) {
+    if (sanitize?.rawHtml === 'sanitize' && typeof sanitize.htmlSanitizer === 'function') {
+        const sanitized = runSanitizer(label, sanitize.htmlSanitizer);
+        if (sanitized !== null) {
+            return sanitized;
+        }
+    }
+    return escapeHtml(label);
+}

package/dist/ListItem/properties.d.ts

@@ -5,7 +5,23 @@ export type ListItemProperties = ListItemEventProperties & {
     rightImageUrl?: string | null;
     /** Rewrites SVG markup before either image is inlined. Providing it enables SVG inlining. */
     transformSvg?: (svg: string) => string;
+    /**
+     * Center text content. Used for the main list item label.
+     *
+     * Rendered as **escaped plain text by default**: `<b>Bold</b>` shows those
+     * characters literally instead of rendering as bold. Pass
+     * `sanitize={{ rawHtml: 'sanitize', htmlSanitizer }}` to render `label` as
+     * markup instead — see `ListItemSanitizeOptions.htmlSanitizer`. A consumer
+     * relying on the library's previous unconditional `{@html label}` behaviour
+     * needs that opt-in now; without it, a label that used to render as markup
+     * renders as visible tag text.
+     */
     label?: string | null;
+    /**
+     * Governs how `label` is rendered when it contains markup. Omitting this
+     * keeps `label` as escaped plain text. See `ListItemSanitizeOptions`.
+     */
+    sanitize?: ListItemSanitizeOptions;
     useAccordion?: boolean;
     rightContentText?: string | null;
     testId?: string;
@@ -31,6 +47,42 @@ export type ListItemProperties = ListItemEventProperties & {
     ariaSelected?: boolean;
     id?: string;
 };
+/**
+ * `label` does not implement HTML sanitization and does not depend on a
+ * sanitizer — the same position `MarkdownText.htmlSanitizer` takes, and for
+ * the same reason: escaping everything is a provably safe default, and a
+ * sanitizer written into this package could only subtract from that safety
+ * while adding a specialist problem (mutation XSS, namespace confusion,
+ * parse-then-reparse divergence) to a dependency this many projects install.
+ */
+export type ListItemSanitizeOptions = {
+    /**
+     * `'escape'` (the default) renders `label` as plain text, with `&`, `<`,
+     * `>`, `"` and `'` escaped. `'sanitize'` renders `label` as markup after
+     * passing it once through `htmlSanitizer`. `'sanitize'` with no
+     * `htmlSanitizer` supplied behaves exactly like `'escape'` — the unsafe
+     * path is unreachable by omission, not by discipline.
+     */
+    rawHtml?: 'escape' | 'sanitize';
+    /**
+     * Sanitizer consulted only while `rawHtml` is `'sanitize'`. Called once,
+     * with the raw `label` string, and whatever it returns is rendered as
+     * markup via `{@html}` — unmodified, since re-checking it would mean
+     * parsing and rewriting the very output this option exists to delegate.
+     *
+     * Pass DOMPurify's `sanitize`, or anything you trust. If it throws or
+     * returns a non-string, `label` is escaped instead; the unsanitized string
+     * is never emitted.
+     *
+     * It must work on the server as well as in the browser: ListItem renders
+     * this through `{@html}` from a `$derived`, so a sanitizer that only works
+     * client-side (DOMPurify without a DOM, say) throws during SSR, falls back
+     * to escaped output there, and succeeds on hydration — the two renders
+     * then disagree. Give it a server implementation, or leave `rawHtml` at
+     * its default on server-rendered pages.
+     */
+    htmlSanitizer?: (html: string) => string;
+};
 export type ListItemEventProperties = {
     onleftimageclick?: (event: MouseEvent) => void;
     onrightimageclick?: (event: MouseEvent) => void;