@juspay/svelte-ui-components 4.51.0 → 4.52.1

package/dist/SankeyChart/properties.d.ts

@@ -64,6 +64,10 @@ export type OptionalSankeyChartProperties = {
      */
     tooltipPortal?: boolean;
     empty?: Snippet;
+    /** Accessible name of the drawing; omit to derive one from the plotted data. */
+    ariaLabel?: string;
+    /** Longer chart description, resolved inside the drawing's own DOM/shadow root. */
+    ariaDescription?: string;
     testId?: string;
     classes?: string;
     /** Labels rendered above each column, indexed by column position (0-based). */

package/dist/Scroller/Scroller.svelte

@@ -3,6 +3,12 @@
   import { prefersReducedMotion } from '../utils';
   import type { ScrollerProperties, ScrollPosition } from './properties';
   import Button from '../Button/Button.svelte';
+  import {
+    contentElements,
+    composedParent,
+    hasTabbableContent,
+    interactiveElements
+  } from '../_interaction/focusable';
   import chevronLeft from '../assets/chevron-left.svg?raw';
   import chevronRight from '../assets/chevron-right.svg?raw';
   import chevronUp from '../assets/chevron-up.svg?raw';
@@ -23,7 +29,8 @@
     arrowPrevious,
     arrowNext,
     onscrollposition,
-    classes
+    classes,
+    ariaLabel
   }: ScrollerProperties = $props();
 
   let containerEl: HTMLDivElement | null = $state(null);
@@ -31,9 +38,38 @@
   let canScrollNext = $state(false);
   let isTouchDevice = $state(false);
   let isDragging = $state(false);
+  let isOverflowing = $state(false);
+  let contentIsTabbable = $state(false);
   let dragStartPos = 0;
   let dragScrollStart = 0;
   let resizeObserver: ResizeObserver | null = null;
+  let mutationObserver: MutationObserver | null = null;
+  let refreshFrame: number | null = null;
+  /** Whether the frame already scheduled must also re-point the observers, not just re-scan. */
+  let refreshRebinds = false;
+
+  /** Pixels one arrow-key press scrolls, close to what a browser's own line scroll does. */
+  const KEY_SCROLL_STEP = 40;
+
+  /**
+   * Attributes whose change can add or remove a Tab stop inside the content. `class` and
+   * `style` are here because showing or hiding a control (`display: none`, `visibility`)
+   * is almost always done through one of them, and that changes whether Tab can reach it
+   * without resizing anything the resize observers watch: a control hidden inside a
+   * fixed-width child leaves every box around it exactly as large as before.
+   */
+  const TAB_ORDER_ATTRIBUTES = [
+    'tabindex',
+    'disabled',
+    'hidden',
+    'inert',
+    'href',
+    'contenteditable',
+    'controls',
+    'open',
+    'class',
+    'style'
+  ];
 
   function getScrollProps(el: HTMLElement) {
     if (direction === 'horizontal') {
@@ -57,6 +93,7 @@
     const { scrollOffset, scrollSize, clientSize } = getScrollProps(containerEl);
     canScrollPrev = scrollOffset > 1;
     canScrollNext = scrollOffset < scrollSize - clientSize - 1;
+    isOverflowing = scrollSize - clientSize > 1;
 
     if (typeof onscrollposition === 'function') {
       const maxScroll = scrollSize - clientSize;
@@ -95,6 +132,54 @@
     scrollBy(1);
   }
 
+  /**
+   * Arrow-key scrolling for the scroll region itself, on its own axis only.
+   *
+   * Browsers scroll a focused overflow element with the arrow keys, but not uniformly
+   * across engines and axes: in WebKit 26.4 a focused vertical region did not respond to
+   * ArrowUp/ArrowDown at all, and the distance and timing of the ones that do scroll differ.
+   * Handling the axis keys here makes the keyboard route do the same thing everywhere.
+   * Only the keys for this component's own axis are taken, so the other axis still scrolls
+   * the page, and only when the region itself holds focus -- a control inside the content
+   * keeps every key it already handles.
+   */
+  function handleRegionKeydown(event: KeyboardEvent) {
+    if (
+      containerEl === null ||
+      event.target !== containerEl ||
+      event.defaultPrevented ||
+      event.altKey ||
+      event.ctrlKey ||
+      event.metaKey ||
+      event.shiftKey
+    ) {
+      return;
+    }
+    const [backwardKey, forwardKey] =
+      direction === 'horizontal' ? ['ArrowLeft', 'ArrowRight'] : ['ArrowUp', 'ArrowDown'];
+    if (event.key !== backwardKey && event.key !== forwardKey) {
+      return;
+    }
+    event.preventDefault();
+    // A mandatory snap point swallows a 40px nudge -- the region settles back where it
+    // started -- so snapping regions move by the same amount the arrow buttons do.
+    const { clientSize } = getScrollProps(containerEl);
+    const step = snapToItem ? (scrollAmount ?? clientSize) : KEY_SCROLL_STEP;
+    const delta = event.key === forwardKey ? step : -step;
+    // Immediate, not animated: a smooth scrollBy measures from wherever the previous
+    // animation currently is, so held or rapid presses fell short of their total in
+    // Firefox (four presses landed at about 115px instead of 160px) while Chromium
+    // reached it. A jump keeps the distance exact in every engine, and is also what the
+    // OS reduced-motion setting asks for.
+    const options: ScrollToOptions = { behavior: 'instant' };
+    if (direction === 'horizontal') {
+      options.left = delta;
+    } else {
+      options.top = delta;
+    }
+    containerEl.scrollBy(options);
+  }
+
   function handleDragStart(event: MouseEvent) {
     if (!dragToScroll || containerEl === null) {
       return;
@@ -151,14 +236,131 @@
     containerEl.style.userSelect = '';
   }
 
+  /**
+   * Re-points both observers at what the region currently contains. The region's own size
+   * is not the only thing that decides overflow: content that grows, shrinks or is swapped
+   * changes `scrollWidth` without resizing the region, so each piece of content is watched
+   * too. Through `<sui-scroller>` the content is slotted light-DOM markup that a mutation
+   * observer on the region cannot see, hence `contentElements` and the per-element
+   * subtree observers.
+   */
+  function observeContent() {
+    if (containerEl === null || resizeObserver === null || mutationObserver === null) {
+      return;
+    }
+    resizeObserver.disconnect();
+    mutationObserver.disconnect();
+    resizeObserver.observe(containerEl);
+    mutationObserver.observe(containerEl, { childList: true, subtree: true, characterData: true });
+    // An enclosing fieldset can disable the only child control without changing
+    // any content box or any attribute inside the region (including slotted WCs).
+    for (
+      let ancestor = composedParent(containerEl);
+      ancestor;
+      ancestor = composedParent(ancestor)
+    ) {
+      mutationObserver.observe(ancestor, {
+        attributes: true,
+        childList: true,
+        attributeFilter: TAB_ORDER_ATTRIBUTES
+      });
+    }
+    for (const element of contentElements(containerEl)) {
+      resizeObserver.observe(element);
+      mutationObserver.observe(element, {
+        childList: true,
+        subtree: true,
+        characterData: true,
+        attributes: true,
+        attributeFilter: TAB_ORDER_ATTRIBUTES
+      });
+    }
+    // A stylesheet can hide or show a control with no write to the content and no change to
+    // any box above: a class on an ancestor outside this component, a media query. The
+    // control itself is the one thing that always changes then -- its box goes to nothing
+    // or comes back -- so each one is watched too, including those hidden right now.
+    for (const control of interactiveElements(containerEl, { includeHidden: true })) {
+      resizeObserver.observe(control);
+    }
+  }
+
+  /** Whether anything inside the content is reachable with Tab right now. */
+  function scanTabbableContent() {
+    if (containerEl !== null) {
+      contentIsTabbable = hasTabbableContent(containerEl);
+    }
+  }
+
+  /**
+   * Content was added, removed or swapped: re-aim the observers at what is there now,
+   * then re-measure and re-scan for Tab stops.
+   */
+  function refreshContent() {
+    if (containerEl === null) {
+      return;
+    }
+    observeContent();
+    updateScrollState();
+    scanTabbableContent();
+  }
+
+  /**
+   * Content kept its structure but may have changed size or visibility -- a class or
+   * inline style hid or showed a control, a media query flipped, the viewport moved.
+   * Re-measures overflow and re-scans Tab stops without re-aiming the observers, which is
+   * the expensive part and unnecessary here. Deliberately does not report a scroll position:
+   * nothing scrolled, and a content element animating its style would otherwise make
+   * `onscrollposition` fire every frame.
+   */
+  function rescanTabOrder() {
+    if (containerEl === null) {
+      return;
+    }
+    const { scrollSize, clientSize } = getScrollProps(containerEl);
+    isOverflowing = scrollSize - clientSize > 1;
+    scanTabbableContent();
+  }
+
+  /** One refresh per frame however many mutations arrive; a structural one wins over a rescan. */
+  function scheduleRefresh(rebind: boolean) {
+    refreshRebinds ||= rebind;
+    if (refreshFrame !== null) {
+      return;
+    }
+    refreshFrame = requestAnimationFrame(() => {
+      refreshFrame = null;
+      const rebinds = refreshRebinds;
+      refreshRebinds = false;
+      if (rebinds) {
+        refreshContent();
+      } else {
+        rescanTabOrder();
+      }
+    });
+  }
+
+  const handleSlotChange = () => scheduleRefresh(true);
+  // A media query can show or hide a control with no change to the DOM or to any box the
+  // observers watch, so a viewport change is its own trigger.
+  const handleWindowResize = () => scheduleRefresh(false);
+
   onMount(() => {
     isTouchDevice = 'ontouchstart' in window || navigator.maxTouchPoints > 0;
     if (containerEl !== null) {
-      updateScrollState();
       resizeObserver = new ResizeObserver(() => {
+        // Content that resizes can fit or overflow, and can also be a control that was
+        // hidden and is now back, so a resize re-scans the Tab order as well as the offsets.
         updateScrollState();
+        scanTabbableContent();
       });
-      resizeObserver.observe(containerEl);
+      mutationObserver = new MutationObserver((records) => {
+        scheduleRefresh(records.some((record) => record.type !== 'attributes'));
+      });
+      refreshContent();
+      // Slot assignment changes (a `sui-scroller` whose slotted content is replaced)
+      // bubble up from the slot element that the web-component wrapper renders.
+      containerEl.addEventListener('slotchange', handleSlotChange);
+      window.addEventListener('resize', handleWindowResize);
 
       if (dragToScroll) {
         window.addEventListener('mousemove', handleDragMove);
@@ -167,6 +369,13 @@
     }
     return () => {
       resizeObserver?.disconnect();
+      mutationObserver?.disconnect();
+      containerEl?.removeEventListener('slotchange', handleSlotChange);
+      window.removeEventListener('resize', handleWindowResize);
+      if (refreshFrame !== null) {
+        cancelAnimationFrame(refreshFrame);
+        refreshFrame = null;
+      }
       if (dragToScroll) {
         window.removeEventListener('mousemove', handleDragMove);
         window.removeEventListener('mouseup', handleDragEnd);
@@ -176,6 +385,17 @@
 
   let showArrowControls = $derived(showArrows && !(hideArrowsOnTouch && isTouchDevice));
   let showGradientOverlay = $derived(showGradient && !(hideArrowsOnTouch && isTouchDevice));
+
+  /**
+   * The region is a Tab stop only while it is the sole keyboard route to its content:
+   * it overflows, no arrow buttons are rendered to scroll it, and nothing inside it is
+   * focusable already (focus moving to such a child scrolls it into view by itself).
+   * Anything else would add a stop that leads nowhere, or one more stop before the
+   * controls that already work.
+   */
+  let regionIsKeyboardRoute = $derived(isOverflowing && !showArrowControls && !contentIsTabbable);
+  // A focusable region must be named; a region the consumer named keeps that name always.
+  let regionLabel = $derived(ariaLabel ?? (regionIsKeyboardRoute ? 'Scrollable content' : null));
 </script>
 
 <div
@@ -209,6 +429,7 @@
   {/if}
 
   <!-- svelte-ignore a11y_no_noninteractive_element_interactions -->
+  <!-- svelte-ignore a11y_no_noninteractive_tabindex -->
   <div
     class="scroll-container"
     class:hide-scrollbar={hideScrollbar}
@@ -217,8 +438,10 @@
     bind:this={containerEl}
     onscroll={updateScrollState}
     onmousedown={dragToScroll ? handleDragStart : null}
+    onkeydown={handleRegionKeydown}
     role="region"
-    tabindex="-1"
+    aria-label={regionLabel}
+    tabindex={regionIsKeyboardRoute ? 0 : -1}
   >
     {@render children()}
   </div>
@@ -348,6 +571,15 @@
     cursor: grabbing;
   }
 
+  /* :focus-visible so a pointer press on the region does not ring it, while the Tab stop
+     it becomes when nothing else can scroll it always does. Inset by default: the ring
+     sits inside the region's own box, so it is not cut off by an `overflow: hidden`
+     ancestor the way an outset ring would be. */
+  .scroll-container:focus-visible {
+    outline: var(--scroller-focus-outline, 2px solid #2563eb);
+    outline-offset: var(--scroller-focus-outline-offset, -2px);
+  }
+
   .arrow {
     display: flex;
     align-items: center;

package/dist/Scroller/properties.d.ts

@@ -24,6 +24,14 @@ export type OptionalScrollerProperties = {
     arrowPrevious?: Snippet;
     arrowNext?: Snippet;
     classes?: string;
+    /**
+     * Accessible name for the scroll region. While the region is the only keyboard route to
+     * overflowing content (no arrows, nothing focusable inside) it is a Tab stop and is named
+     * `Scrollable content` unless this says otherwise; a region given a name keeps it whether
+     * or not it is currently a Tab stop. Prefer a name that says what scrolls, e.g.
+     * `Release timeline`.
+     */
+    ariaLabel?: string;
 };
 export type ScrollerEventProperties = {
     onscrollposition?: (position: ScrollPosition) => void;

package/dist/Select/Select.svelte

@@ -18,6 +18,7 @@
     searchPosition = 'trigger',
     placeholder = '',
     ariaLabel,
+    ariaLabelledby,
     disabled = false,
     error = false,
     errorMessage,
@@ -76,7 +77,7 @@
   let placementRequest: SelectPlacement = $derived(
     placement ?? (dropdownAlign === 'right' ? 'bottom-right' : 'bottom-left')
   );
-  let placementPinned: boolean = $derived(placement != null);
+  let placementPinned: boolean = $derived(placement != null && placement !== 'auto');
 
   /** Corner an `'auto'` measuring pass settled on; null until it has run. */
   let autoResolved: Exclude<SelectPlacement, 'auto'> | null = $state(null);
@@ -161,6 +162,22 @@
     })
   );
 
+  /* The field's name, applied to every element a user can land on: the combobox
+     trigger, the text input that replaces its label when the filter lives in the
+     trigger (which is the control that actually takes focus there, and would
+     otherwise be named only by its placeholder), and the listbox they open.
+     Blank strings are dropped rather than emitted, so `aria-label=""` can never
+     erase the name an element would otherwise get. The component API gives
+     `ariaLabel` priority over `ariaLabelledby`, following Slider's contract. */
+  const accessibleName = $derived(
+    typeof ariaLabel === 'string' && ariaLabel.trim() !== '' ? ariaLabel : null
+  );
+  const accessibleLabelledby = $derived(
+    accessibleName === null && typeof ariaLabelledby === 'string' && ariaLabelledby.trim() !== ''
+      ? ariaLabelledby.trim()
+      : null
+  );
+
   /* Nothing selected means nothing to clear, so the control is not rendered at
      all rather than rendered inert -- a disabled × that never enables reads as
      broken. Same for `disabled`, where the whole field is inert already. */
@@ -316,8 +333,8 @@
       dropdown: { width: dropdownWidth, height: dropdownHeight },
       viewport,
       align: placementAlign,
-      /* Unset `placement` keeps the fit-based flip this path always had; a pinned
-         corner is honoured on both axes instead. */
+      /* Unset and explicit 'auto' placements keep the fit-based flip and viewport
+         clamp; only a caller-pinned corner overrides the vertical fit. */
       vertical: placementPinned
         ? resolvedPlacement === 'top-left' || resolvedPlacement === 'top-right'
           ? 'top'
@@ -680,7 +697,19 @@
       return;
     }
     query = event.target.value;
-    if (!open) {
+    /* An input event is only a request to open when the field it came from can be
+       typed into while the panel is closed -- the in-trigger input, whose typing
+       is how a closed Select opens. The in-menu search box exists only while the
+       panel is open, so an event arriving from it with `open` already false is
+       not the user typing: it is the browser clearing the field as Escape
+       dismisses the panel. Firefox does that for an <input type="search"> and
+       dispatches the input event synchronously inside the same keydown, before
+       Svelte has flushed the close to the DOM -- so honouring it re-opened the
+       panel that Escape had just closed (and fired onopen straight after
+       onclose), leaving aria-expanded true and the next trigger click toggling
+       it shut. Chromium clears after the flush and WebKit does not clear at all,
+       which is why only Firefox showed it. */
+    if (!open && !searchInMenu) {
       openDropdown();
     }
     highlightedIndex = -1;
@@ -755,10 +784,12 @@
       onclick={handleTriggerClick}
       onkeydown={handleKeydown}
       role="combobox"
-      aria-label={ariaLabel}
       aria-expanded={open}
       aria-haspopup="listbox"
       aria-controls={listboxId}
+      aria-label={accessibleName}
+      aria-labelledby={accessibleLabelledby}
+      aria-disabled={disabled ? 'true' : null}
       aria-invalid={field.ariaInvalid}
       aria-describedby={field.describedBy}
       {...highlightedOptionId !== null ? { 'aria-activedescendant': highlightedOptionId } : {}}
@@ -781,13 +812,14 @@
             <input
               class="select-search"
               type="text"
-              aria-label={ariaLabel}
               value={query}
               oninput={handleSearchInput}
               onfocus={handleSearchFocus}
               bind:this={searchInputEl}
               placeholder={value.length === 0 ? placeholder : ''}
               {disabled}
+              aria-label={accessibleName}
+              aria-labelledby={accessibleLabelledby}
               aria-invalid={field.ariaInvalid}
               aria-describedby={field.describedBy}
               autocomplete="off"
@@ -810,13 +842,14 @@
             <input
               class="select-search"
               type="text"
-              aria-label={ariaLabel}
               value={query}
               oninput={handleSearchInput}
               onfocus={handleSearchFocus}
               bind:this={searchInputEl}
               placeholder={value.length === 0 ? placeholder : ''}
               {disabled}
+              aria-label={accessibleName}
+              aria-labelledby={accessibleLabelledby}
               aria-invalid={field.ariaInvalid}
               aria-describedby={field.describedBy}
               autocomplete="off"
@@ -832,13 +865,14 @@
         <input
           class="select-search"
           type="text"
-          aria-label={ariaLabel}
           value={open ? query : displayText}
           oninput={handleSearchInput}
           onfocus={handleSearchFocus}
           bind:this={searchInputEl}
           placeholder={searchPlaceholder}
           {disabled}
+          aria-label={accessibleName}
+          aria-labelledby={accessibleLabelledby}
           aria-invalid={field.ariaInvalid}
           aria-describedby={field.describedBy}
           autocomplete="off"
@@ -1059,6 +1093,8 @@
           class="select-menu-list"
           role="listbox"
           id={listboxId}
+          aria-label={accessibleName}
+          aria-labelledby={accessibleLabelledby}
           aria-multiselectable={multiple}
           tabindex="-1"
         >
@@ -1088,6 +1124,8 @@
         bind:clientHeight={dropdownHeight}
         role="listbox"
         id={listboxId}
+        aria-label={accessibleName}
+        aria-labelledby={accessibleLabelledby}
         aria-multiselectable={multiple}
         style={portalStyle}
         use:portalToRoot

package/dist/Select/properties.d.ts

@@ -55,8 +55,24 @@ export type OptionalSelectProperties = {
      */
     searchPosition?: SelectSearchPosition;
     placeholder?: string;
-    /** Accessible name for the combobox trigger. Omitted to preserve the default unnamed behavior. */
+    /**
+     * Names the field for assistive tech, as `aria-label` on the combobox trigger
+     * (and on the text input inside it for `searchable` with the input in the
+     * trigger, which is the control that actually takes focus there, and on the
+     * open listbox). The placeholder and the selected option are the value, not
+     * the field's identity, so a Select with neither visible label text nor this
+     * announces only "Choose a fruit, combobox" or "Apple, combobox".
+     * The name does not change with the selection, so it stays meaningful when
+     * the Select is empty, selected, invalid or disabled.
+     */
     ariaLabel?: string;
+    /**
+     * Ids of the elements that name the field (`aria-labelledby`), for a label that is
+     * already on screen. `ariaLabel` wins if both are given. Ids resolve in the same
+     * DOM root as the Select; for `<sui-select>` the wrapper resolves them from the
+     * host's root, because an id reference does not cross a shadow boundary.
+     */
+    ariaLabelledby?: string;
     disabled?: boolean;
     /**
      * Renders the error treatment on the trigger — a red border that outranks

package/dist/Sheet/Sheet.svelte

@@ -3,14 +3,16 @@
   import type { SheetProperties } from './properties';
   import { fade } from 'svelte/transition';
   import { tokenizedFly } from '../Animations/tokenizedFly';
-  import { lockBodyScroll, unlockBodyScroll } from '../utils';
-  import { tick } from 'svelte';
+  import { acquireScrollLock, resolveScrollContainer } from '../utils';
+  import { tick, onMount, untrack } from 'svelte';
+  import { toStore } from 'svelte/store';
   import Button from '../Button/Button.svelte';
   import { focusTrapTabTarget, getActiveElement } from '../_interaction/focus';
   import { registerDismissible } from '../_interaction/dismissal';
 
   let {
     open = $bindable(false),
+    scrollContainer,
     side = 'right',
     title,
     showOverlay = true,
@@ -150,6 +152,27 @@
     }
   }
 
+  let scrollLockNode: HTMLElement | null = null;
+  let releaseScrollLock: (() => void) | null = null;
+  let scrollLockSpanEnded = false;
+
+  onMount(() =>
+    toStore(() => open).subscribe((isOpen) => {
+      if (!isOpen) {
+        scrollLockSpanEnded = true;
+      } else if (scrollLockSpanEnded && scrollLockNode !== null) {
+        // Reversing an outro reuses the action. Resolve the next logical open's
+        // owner without subscribing to ownership changes during that open.
+        scrollLockSpanEnded = false;
+        const releaseNext = untrack(() =>
+          acquireScrollLock(resolveScrollContainer(scrollLockNode, scrollContainer))
+        );
+        releaseScrollLock?.();
+        releaseScrollLock = releaseNext;
+      }
+    })
+  );
+
   function scrollLockAction(node: HTMLElement) {
     // getActiveElement rather than document.activeElement: when the sheet is
     // used through its custom element the opener lives inside a shadow root,
@@ -157,7 +180,9 @@
     // could never be handed focus back.
     const previousFocus = getActiveElement(node);
     let active = true;
-    lockBodyScroll();
+    scrollLockNode = node;
+    scrollLockSpanEnded = false;
+    releaseScrollLock = acquireScrollLock(resolveScrollContainer(node, scrollContainer));
     // Registered here rather than in an onMount/onDestroy pair: this action's
     // mount/destroy already brackets exactly the open span (the overlay only
     // exists while `open` is true, per the `{#if open}` below), the same
@@ -177,7 +202,9 @@
       destroy() {
         active = false;
         releaseDismissible();
-        unlockBodyScroll();
+        releaseScrollLock?.();
+        releaseScrollLock = null;
+        scrollLockNode = null;
         // Only take focus back when it is still somewhere the sheet is
         // responsible for -- inside the panel, or nowhere at all. If the user
         // has already moved on to another control, stealing it back would be

package/dist/Sheet/properties.d.ts

@@ -1,3 +1,4 @@
+import type { ScrollContainer } from '../types';
 import type { Snippet } from 'svelte';
 export type SheetSide = 'left' | 'right' | 'top' | 'bottom' | 'center';
 export type SheetProperties = MandatorySheetProperties & OptionalSheetProperties & SheetEventProperties;
@@ -5,6 +6,11 @@ export type MandatorySheetProperties = {
     content: Snippet;
 };
 export type OptionalSheetProperties = {
+    /** Scroll owner, resolved once per open span. Omit for the overlay's ownerDocument.body.
+     * Supply the embedded scroll element or a getter; explicit null means no lock.
+     * Changing ownership while open takes effect on the next open, and teardown
+     * always releases the originally acquired container. */
+    scrollContainer?: ScrollContainer;
     open?: boolean;
     side?: SheetSide;
     title?: string;

package/dist/SplitInput/SplitInput.svelte

@@ -2,6 +2,7 @@
   import { tick } from 'svelte';
   import { describeField } from '../_field/description';
   import Input from '../Input/Input.svelte';
+  import { resolveFieldName } from './field-name';
   import type { FieldConfig, SplitInputProperties } from './properties';
 
   let {
@@ -14,6 +15,7 @@
     testId,
     classes,
     ariaLabel,
+    positionLabel,
     errorMessage,
     infoMessage,
     invalid = false,
@@ -43,6 +45,20 @@
 
   let fieldCount = $derived(typeof fields !== 'undefined' ? fields.length : length);
 
+  /* A box is named by what it is, not left to the group's name alone: see
+     `resolveFieldName` for the precedence. Each box is an `Input` with
+     `actionInput`, which never renders Input's own <label>, so `ariaLabel` on the
+     inner Input is the only way its name can be set. */
+  function fieldName(index: number, config: FieldConfig): string {
+    return resolveFieldName({
+      index,
+      total: fieldCount,
+      config,
+      groupLabel: ariaLabel,
+      positionLabel
+    });
+  }
+
   let fieldConfigs: FieldConfig[] = $derived(
     typeof fields !== 'undefined'
       ? fields
@@ -273,6 +289,7 @@
         validators={config.validators ?? []}
         autoComplete={config.autoComplete ?? 'on'}
         inputMode={config.inputMode}
+        ariaLabel={fieldName(index, config)}
         disable={disabled}
         actionInput={true}
         classes="field-group-input"

package/dist/SplitInput/field-name.d.ts

@@ -0,0 +1,29 @@
+import type { FieldConfig } from './properties';
+type NamedFieldConfig = Pick<FieldConfig, 'ariaLabel' | 'label' | 'dataType' | 'maxLength'>;
+export type FieldNameContext = {
+    readonly index: number;
+    readonly total: number;
+    readonly config: NamedFieldConfig;
+    /** The group's own name (`SplitInput`'s `ariaLabel`), when it has one. */
+    readonly groupLabel?: string;
+    readonly positionLabel?: (position: number, total: number) => string;
+};
+/**
+ * The accessible name for one box of a SplitInput.
+ *
+ * A box on its own is meaningless -- "edit text, blank", six times -- so each one
+ * has to say which field it is. In order of how specific the caller was:
+ *
+ * 1. `config.ariaLabel`: the caller named this box by purpose ("Red", "Area
+ *    code"). Used exactly as given; it already says which field it is.
+ * 2. `config.label`: the visible caption under the box ("R"), which is what the
+ *    box is already called on screen -- the name has to contain it.
+ * 3. Otherwise the box's position: "digit 2 of 6".
+ *
+ * For 2 and 3 the group's name leads, because a screen reader's form-field list
+ * shows each control without its group: "One-time code, digit 2 of 6" is
+ * identifiable there, "digit 2 of 6" is not. With no group name the position is
+ * all there is, so the group should be named -- see `SplitInput`'s `ariaLabel`.
+ */
+export declare const resolveFieldName: ({ index, total, config, groupLabel, positionLabel }: FieldNameContext) => string;
+export {};