@juspay/svelte-ui-components 4.9.2 → 4.10.1

package/dist/Checkbox/Checkbox.svelte

@@ -19,6 +19,23 @@
     attributes
   }: CheckboxProperties = $props();
 
+  // Visible text wins over `ariaLabel`, which is what `properties.ts` has always
+  // promised and what WCAG 2.5.3 requires: a control showing "Accept terms" must
+  // carry that text in its accessible name, so letting an explicit label replace
+  // it outright would swap the name a speech-input user says for one they cannot
+  // see. `ariaLabel` names the box only when there is no visible text to use —
+  // the icon-only and label-in-a-table-header cases it exists for.
+  //
+  // A blank `ariaLabel` is treated as absent rather than as an empty name, since
+  // `aria-label=""` leaves the box unnamed, which is the bug this fixes.
+  const accessibleName: string | null = $derived(
+    text.length > 0
+      ? text
+      : typeof ariaLabel === 'string' && ariaLabel.trim() !== ''
+        ? ariaLabel
+        : null
+  );
+
   function handleClick(): void {
     if (disabled) {
       return;
@@ -82,7 +99,7 @@
     aria-checked={indeterminate ? 'mixed' : checked}
     aria-disabled={disabled}
     aria-controls={ariaControls ?? null}
-    aria-label={text.length === 0 ? (ariaLabel ?? null) : null}
+    aria-label={accessibleName}
     onkeydown={handleKeyDown}
     data-pw={typeof testId === 'string' ? `${testId}-box` : null}
     testID={typeof testId === 'string' ? `${testId}-box` : null}

package/dist/CommandMenu/CommandMenu.svelte

@@ -19,10 +19,19 @@
     classes
   }: CommandMenuProperties = $props();
 
+  // Stable per-instance ids keep ARIA references distinct across menus.
+  const uid = $props.id();
+  const listboxId = `command-menu-listbox-${uid}`;
+
   let query = $state('');
   let activeIndex = $state(0);
   let inputElement: HTMLInputElement | null = $state(null);
   let listElement: HTMLDivElement | null = $state(null);
+  let dialogElement: HTMLDivElement | null = $state(null);
+  // Captured when the dialog opens, consumed once it unmounts — mirrors
+  // Gallery.svelte's lightboxAction so focus returns to whatever opened the
+  // command menu instead of falling back to <body>.
+  let openerElement: HTMLElement | null = null;
 
   let filteredItems = $derived.by(() => {
     if (query.trim() === '') {
@@ -68,6 +77,13 @@
     return map;
   });
 
+  // aria-activedescendant must point at the id of the highlighted option, which
+  // is keyed by its flat index (see the option's own id below) — null once the
+  // list is empty, since there is then no option to describe.
+  let activeDescendantId = $derived(
+    flatItems.length > 0 ? `command-menu-option-${uid}-${activeIndex}` : null
+  );
+
   function close() {
     open = false;
     query = '';
@@ -132,9 +148,47 @@
         close();
         break;
       }
+      case 'Tab': {
+        // aria-modal="true" promises focus stays inside, so Tab cycles rather
+        // than escaping. Cycle over whatever is actually tabbable instead of
+        // pinning to the input: today the input is the only tab stop (options
+        // are tabindex="-1" and are reached with arrows), so the two are
+        // equivalent — but pinning would silently break the moment the dialog
+        // gains a second tab stop, such as a close button.
+        const tabbable = tabbableElements();
+        if (tabbable.length === 0) {
+          break;
+        }
+        event.preventDefault();
+        const active = document.activeElement;
+        const current = active instanceof HTMLElement ? tabbable.indexOf(active) : -1;
+        const step = event.shiftKey ? -1 : 1;
+        const next = (current + step + tabbable.length) % tabbable.length;
+        tabbable.at(next)?.focus();
+        break;
+      }
     }
   }
 
+  // Everything inside the dialog that Tab would normally reach. `tabindex="-1"`
+  // is excluded because those are arrow-key targets, not tab stops.
+  function tabbableElements(): HTMLElement[] {
+    if (dialogElement === null) {
+      return [];
+    }
+    const candidates = dialogElement.querySelectorAll<HTMLElement>(
+      'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]'
+    );
+    return [...candidates].filter(
+      (el) =>
+        // The options are real <button>s held out of the tab order with
+        // tabindex="-1"; they are arrow-key targets. Excluding -1 only in the
+        // `[tabindex]` selector would still match them as buttons.
+        el.getAttribute('tabindex') !== '-1' &&
+        (el.offsetParent !== null || el === document.activeElement)
+    );
+  }
+
   async function scrollActiveIntoView() {
     await tick();
     if (listElement !== null) {
@@ -167,6 +221,9 @@
   // onDestroy below must NOT unlock as well: with a shared reference count a second
   // decrement would release a lock another open surface still needs.
   function scrollLockAction(_node: HTMLElement) {
+    if (openerElement === null && document.activeElement instanceof HTMLElement) {
+      openerElement = document.activeElement;
+    }
     lockBodyScroll();
     tick().then(() => {
       if (inputElement !== null) {
@@ -176,6 +233,10 @@
     return {
       destroy() {
         unlockBodyScroll();
+        if (openerElement !== null) {
+          openerElement.focus();
+          openerElement = null;
+        }
       }
     };
   }
@@ -204,7 +265,7 @@
     data-pw={typeof testId === 'string' ? testId : null}
     testID={typeof testId === 'string' ? testId : null}
   >
-    <div class="command-menu-dialog">
+    <div class="command-menu-dialog" bind:this={dialogElement}>
       <div class="command-menu-input-wrapper">
         {#if typeof searchIcon === 'function'}
           {@render searchIcon()}
@@ -223,6 +284,11 @@
           {placeholder}
           autocomplete="off"
           spellcheck="false"
+          role="combobox"
+          aria-expanded={flatItems.length > 0}
+          aria-controls={listboxId}
+          aria-autocomplete="list"
+          aria-activedescendant={activeDescendantId}
           data-pw={typeof testId === 'string' ? `${testId}-input` : null}
           testID={typeof testId === 'string' ? `${testId}-input` : null}
         />
@@ -230,7 +296,7 @@
 
       <div class="command-menu-separator"></div>
 
-      <div class="command-menu-list" bind:this={listElement} role="listbox">
+      <div class="command-menu-list" bind:this={listElement} id={listboxId} role="listbox">
         {#if flatItems.length === 0}
           <div class="command-menu-empty">
             {emptyText}
@@ -244,6 +310,7 @@
               {@const index = flatIndexLookup.get(item.value) ?? -1}
               <button
                 type="button"
+                id={`command-menu-option-${uid}-${index}`}
                 class="command-menu-item"
                 class:active={index === activeIndex}
                 class:disabled={item.disabled}

package/dist/ContextMenu/ContextMenu.svelte

@@ -19,27 +19,66 @@
   let focusedIndex: number = $state(-1);
   let posX: number = $state(0);
   let posY: number = $state(0);
+  // Captured when the menu opens, consumed once on close — the element that had
+  // focus (or triggered the native contextmenu event) is where focus belongs once
+  // the menu goes away, matching Menu.svelte's own restore-on-close contract.
+  let openerElement: HTMLElement | null = $state(null);
 
   let selectableItems: ContextMenuItem[] = $derived(
     items.filter((item) => !item.separator && !item.disabled)
   );
 
+  // The frame that moves focus into the freshly-opened menu, kept so closing can
+  // cancel it. Escape pressed between the right-click and that frame used to
+  // leave the callback queued: it ran after the menu was gone, moved focus onto
+  // an item that no longer existed, and left the page with nothing focused at
+  // all — worse than never restoring, because the user's place is simply lost.
+  let openFrame: number | null = null;
+
+  function cancelOpenFrame() {
+    if (openFrame !== null) {
+      cancelAnimationFrame(openFrame);
+      openFrame = null;
+    }
+  }
+
   function openMenu(x: number, y: number) {
     posX = x;
     posY = y;
     open = true;
     focusedIndex = 0;
     onopen?.();
-    requestAnimationFrame(() => {
+    cancelOpenFrame();
+    openFrame = requestAnimationFrame(() => {
+      openFrame = null;
       adjustPosition();
       focusItem(0);
     });
   }
 
   function close() {
+    cancelOpenFrame();
     open = false;
     focusedIndex = -1;
     onclose?.();
+
+    const opener = openerElement;
+    openerElement = null;
+    if (opener === null) {
+      return;
+    }
+
+    // Only take focus back if nothing else has claimed it. Closing by clicking a
+    // focusable element outside means the browser has already moved focus there,
+    // and pulling it back to the opener would fight the user and lose their
+    // place. Focus still inside the dying menu, or fallen to <body>, is loose and
+    // does belong to the opener.
+    const active = document.activeElement;
+    const focusIsLoose =
+      active === null || active === document.body || (menuEl?.contains(active) ?? false);
+    if (focusIsLoose) {
+      opener.focus();
+    }
   }
 
   function selectMenuItem(item: ContextMenuItem) {
@@ -90,6 +129,12 @@
 
   function handleContextMenu(event: MouseEvent) {
     event.preventDefault();
+    // A right-click usually leaves <body> as the active element, and "restore
+    // focus to <body>" is not a restoration — it is the same as doing nothing,
+    // but it also discards whatever the browser would have done. Capture only a
+    // real element.
+    const active = document.activeElement;
+    openerElement = active instanceof HTMLElement && active !== document.body ? active : null;
     openMenu(event.clientX, event.clientY);
   }
 
@@ -147,13 +192,28 @@
     }
   }
 
+  // Escape is handled on the document as well as on the menu, because for one
+  // frame after the right-click the menu is open but focus has not moved into it
+  // yet. A menu-only handler does nothing during that window: the keystroke is
+  // swallowed, the menu stays open, and the pending frame then pulls focus into
+  // it — so a quick Escape appeared to do the opposite of what it asked for. An
+  // open menu should close on Escape wherever focus happens to be.
+  function handleDocumentKeydown(event: KeyboardEvent) {
+    if (open && event.key === 'Escape') {
+      event.preventDefault();
+      close();
+    }
+  }
+
   onMount(() => {
     document.addEventListener('click', handleClickOutside);
+    document.addEventListener('keydown', handleDocumentKeydown);
   });
 
   onDestroy(() => {
     if (typeof window !== 'undefined') {
       document.removeEventListener('click', handleClickOutside);
+      document.removeEventListener('keydown', handleDocumentKeydown);
     }
   });
 </script>
@@ -162,7 +222,7 @@
   class="context-menu-container {classes ?? ''}"
   bind:this={containerEl}
   oncontextmenu={handleContextMenu}
-  role="application"
+  {...open ? { role: 'application' } : {}}
   data-pw={testId}
   testID={testId}
 >

package/dist/Slider/Slider.svelte

@@ -10,6 +10,7 @@
     showValue = false,
     labelFormatter,
     ariaLabel,
+    ariaLabelledby,
     testId,
     onchange,
     oninput,
@@ -44,6 +45,7 @@
     {value}
     {disabled}
     aria-label={typeof ariaLabel === 'string' ? ariaLabel : null}
+    aria-labelledby={typeof ariaLabel === 'string' ? null : (ariaLabelledby ?? null)}
     data-pw={typeof testId === 'string' ? testId : null}
     testID={typeof testId === 'string' ? testId : null}
     oninput={handleInput}

package/dist/Slider/properties.d.ts

@@ -14,6 +14,13 @@ export type OptionalSliderProperties = {
      * so a control whose purpose is not carried by adjacent visible text needs this.
      */
     ariaLabel?: string;
+    /**
+     * Ids of the elements that name the range input (aria-labelledby). Use this
+     * instead of `ariaLabel` when the name is already on screen, so the two cannot
+     * drift apart. `ariaLabel` wins if both are given, matching how the platform
+     * resolves them.
+     */
+    ariaLabelledby?: string;
     testId?: string;
     classes?: string;
 };

package/dist/SplitButton/SplitButton.svelte

@@ -12,12 +12,27 @@
     testId,
     dropdownIcon,
     classes,
+    triggerAriaLabel,
     onclick,
     onselect
   }: SplitButtonProperties = $props();
 
   let menuOpen = $state(false);
 
+  // The dropdown trigger renders a chevron and nothing else, so without a name it is a
+  // focusable control that announces as an unnamed button.
+  // A blank `triggerAriaLabel` falls back rather than being honoured: `??` only
+  // rejects null and undefined, so an empty string would have been passed
+  // through as `aria-label=""` and left the trigger unnamed — the very thing
+  // this generated fallback exists to prevent.
+  let resolvedTriggerAriaLabel = $derived(
+    typeof triggerAriaLabel === 'string' && triggerAriaLabel.trim() !== ''
+      ? triggerAriaLabel
+      : text.length > 0
+        ? `More ${text} options`
+        : 'More options'
+  );
+
   function handlePrimaryClick(event: MouseEvent): void {
     if (disabled) {
       return;
@@ -40,7 +55,12 @@
     <Button {text} onclick={handlePrimaryClick} {disabled} />
   </div>
   <div class="split-button-trigger">
-    <Menu {items} bind:open={menuOpen} onselect={handleMenuSelect}>
+    <Menu
+      {items}
+      bind:open={menuOpen}
+      triggerAriaLabel={resolvedTriggerAriaLabel}
+      onselect={handleMenuSelect}
+    >
       {#snippet trigger()}
         <span class="split-button-arrow">
           {#if typeof dropdownIcon === 'function'}

package/dist/SplitButton/properties.d.ts

@@ -10,6 +10,13 @@ export type OptionalSplitButtonProperties = {
     testId?: string;
     dropdownIcon?: Snippet;
     classes?: string;
+    /**
+     * Accessible name for the dropdown trigger — the second control, which shows only a
+     * chevron and so has no text to be named by. Defaults to `More <text> options`, which
+     * distinguishes it from the primary button beside it. Named after Menu's own
+     * `triggerAriaLabel`, which is what it forwards to.
+     */
+    triggerAriaLabel?: string;
 };
 export type SplitButtonEventProperties = {
     onclick?: (event: MouseEvent) => void;

package/dist/Stepper/Step.svelte

@@ -16,6 +16,12 @@
     onkeydown
   }: StepProperties = $props();
 
+  // Per-instance, because `step-label-${stepIndex}` collides across two Steppers
+  // on one page and `aria-labelledby` then resolves to whichever matching id
+  // comes first in the document — naming a step after a different Stepper's.
+  const uid = $props.id();
+  const labelId = `step-label-${uid}`;
+
   const handleStepClick = (): void => {
     onclick?.({ selectedIndex: stepIndex });
   };
@@ -59,7 +65,7 @@
   role={suppressRoleAndTabindex ? null : 'button'}
   tabindex={suppressRoleAndTabindex ? null : 0}
   aria-label={ariaLabel ?? null}
-  aria-labelledby={ariaLabel ? null : `step-label-${stepIndex}`}
+  aria-labelledby={ariaLabel ? null : labelId}
   aria-current={status === 'active' ? 'step' : null}
 >
   {#if typeof icon === 'string' && icon.length > 0}
@@ -99,7 +105,7 @@
     </div>
   {/if}
 
-  <div class="step-text" id="step-label-{stepIndex}">
+  <div class="step-text" id={labelId}>
     {label}
   </div>
 

package/dist/Table/BuiltinCell.svelte

@@ -447,11 +447,16 @@
           }))}
           testId={generatedTestId('menu', rowIndex)}
           {usePortal}
+          interactiveTrigger
           onselect={(menuItem) => column.onMenuAction?.(rowIndex, menuItem.value, originalIndex)}
         >
-          {#snippet trigger()}
+          {#snippet trigger(triggerProps)}
             <span class="builtin-icon-button">
-              <Button ariaLabel="More actions" testId={generatedTestId('menuTrigger', rowIndex)}>
+              <Button
+                {...triggerProps}
+                ariaLabel="More actions"
+                testId={generatedTestId('menuTrigger', rowIndex)}
+              >
                 {#snippet icon()}
                   <!-- eslint-disable svelte/no-at-html-tags -->
                   <span class="builtin-menu-dots">{@html dotsSvg}</span>
@@ -483,11 +488,13 @@
         }))}
         testId={generatedTestId('popup', rowIndex)}
         {usePortal}
+        interactiveTrigger
         onselect={(menuItem) => column.onMenuAction?.(rowIndex, menuItem.value, originalIndex)}
       >
-        {#snippet trigger()}
+        {#snippet trigger(triggerProps)}
           <span class="builtin-icon-button">
             <Button
+              {...triggerProps}
               ariaLabel={popupData.ariaLabel ?? 'More actions'}
               testId={generatedTestId('popupTrigger', rowIndex)}
             >

package/dist/Table/Table.svelte

@@ -758,19 +758,21 @@
                           }))}
                           selectedValue={filter.selectedValue ?? null}
                           role="listbox"
+                          interactiveTrigger
                           testId={headerColumn.testId && `${headerColumn.testId}-filter`}
                           onselect={(menuItem) =>
                             filter.onFilterChange?.(
                               menuItem.value === filter.selectedValue ? null : menuItem.value
                             )}
                         >
-                          {#snippet trigger()}
+                          {#snippet trigger(triggerProps)}
                             <span
                               class="table-header-filter-trigger"
                               class:table-header-filter-active={typeof filter.selectedValue ===
                                 'string'}
                             >
                               <Button
+                                {...triggerProps}
                                 ariaLabel="Filter by {header}"
                                 testId={headerColumn.testId &&
                                   `${headerColumn.testId}-filter-trigger`}