@juspay/svelte-ui-components 4.27.6 → 4.28.0

package/dist/Choicebox/group.js

@@ -0,0 +1,127 @@
+/**
+ * Mutual exclusion and arrow-key roving for `Choicebox`es that share a `name`.
+ *
+ * A native radio group is a browser behaviour rather than a component one: the
+ * browser finds the other `<input type="radio">`s carrying the same name and
+ * unchecks them. Choicebox's selection lives in a per-instance `selected` prop,
+ * so nothing was doing that job -- two cards a consumer thought of as one group
+ * could both be selected, and a keyboard user tabbed through every card instead
+ * of arrowing between them, which is not how a radio group behaves.
+ *
+ * Membership is keyed by name AND by root node, so two forms on one page that
+ * both use `name="plan"` stay separate groups and a card inside a shadow root
+ * does not join one in the document. That is narrower than the platform, which
+ * scopes a radio group to the owning form; form ownership is not readable from
+ * a card that may not be inside a form at all, and the root node is the closest
+ * boundary that always exists.
+ *
+ * The registry is imperative on purpose. Roving tabindex is a property of the
+ * WHOLE group -- the single tab stop moves when any member's selection or
+ * disabled state changes -- and a per-instance `$derived` cannot observe a
+ * sibling's props. Each member re-registers whenever its own inputs change,
+ * which is what re-runs the group-wide recalculation below.
+ */
+const registry = new Set();
+/** Members of `member`'s group, in DOM order. */
+function groupOf(member) {
+    const root = member.element.getRootNode();
+    return [...registry]
+        .filter((other) => other.name === member.name && other.element.getRootNode() === root)
+        .sort((a, b) => (a.element.compareDocumentPosition(b.element) & Node.DOCUMENT_POSITION_FOLLOWING) !== 0
+        ? -1
+        : 1);
+}
+/**
+ * One tab stop per group, on the selected card -- or on the first enabled card
+ * while nothing is selected, which is what keeps an untouched group reachable
+ * by Tab at all.
+ */
+function refreshRoving(group) {
+    const enabled = group.filter((candidate) => !candidate.isDisabled());
+    const tabbable = enabled.find((candidate) => candidate.isSelected()) ?? enabled.at(0) ?? null;
+    for (const member of group) {
+        member.element.tabIndex = member.isDisabled() ? -1 : member === tabbable ? 0 : -1;
+    }
+}
+/**
+ * Adds a card to the group named `name`. Returns the function that removes it
+ * again; both ends recalculate the group's tab stop, so a card unmounting while
+ * it held the tab stop hands it on rather than leaving the group unreachable.
+ */
+export function joinChoiceboxGroup(name, member) {
+    const registration = { ...member, name };
+    registry.add(registration);
+    refreshRoving(groupOf(registration));
+    return () => {
+        registry.delete(registration);
+        refreshRoving(groupOf(registration));
+    };
+}
+/** The registration this element was added under, or null when ungrouped. */
+function registrationFor(element) {
+    for (const candidate of registry) {
+        if (candidate.element === element) {
+            return candidate;
+        }
+    }
+    return null;
+}
+/**
+ * Selects one card and deselects the rest, the way checking a native radio
+ * unchecks its group. Siblings are told through `setSelected` so a consumer
+ * binding `selected` on each card sees the change, and through `notify` so a
+ * consumer listening on `onclick` is not left believing a deselected card is
+ * still selected.
+ */
+export function selectExclusively(element) {
+    const registration = registrationFor(element);
+    if (registration === null) {
+        return;
+    }
+    const group = groupOf(registration);
+    for (const member of group) {
+        if (member === registration || !member.isSelected()) {
+            continue;
+        }
+        member.setSelected(false);
+        member.notify(false);
+    }
+    registration.setSelected(true);
+    refreshRoving(group);
+}
+/**
+ * Arrow-key movement inside a radio group. Moving selects, which is what a
+ * native radio group does and what makes the group usable without a mouse: the
+ * arrow keys are the only way to change the choice once Tab has entered it.
+ *
+ * Returns false when the element is not in a group, so the caller can leave the
+ * key alone rather than swallowing it.
+ */
+export function moveWithinChoiceboxGroup(element, step) {
+    const registration = registrationFor(element);
+    if (registration === null) {
+        return false;
+    }
+    const enabled = groupOf(registration).filter((candidate) => !candidate.isDisabled());
+    if (enabled.length === 0) {
+        return false;
+    }
+    const current = enabled.indexOf(registration);
+    if (current === -1) {
+        return false;
+    }
+    const target = step === 'first'
+        ? enabled.at(0)
+        : step === 'last'
+            ? enabled.at(-1)
+            : // Wraps, like a native radio group: arrowing past the last member
+                // returns to the first rather than stopping dead.
+                enabled.at((current + (step === 'next' ? 1 : -1) + enabled.length) % enabled.length);
+    if (typeof target === 'undefined' || target === registration) {
+        return true;
+    }
+    selectExclusively(target.element);
+    target.notify(true);
+    target.element.focus();
+    return true;
+}

package/dist/Choicebox/properties.d.ts

@@ -9,6 +9,52 @@ export type OptionalChoiceboxProperties = {
     showIndicator?: boolean;
     testId?: string;
     classes?: string;
+    /**
+     * Text shown, and announced, when the card is in error. Linked to the card
+     * through `aria-describedby`, and sets `aria-invalid` while present.
+     */
+    errorMessage?: string | null;
+    /**
+     * Persistent helper text describing the card. Linked through
+     * `aria-describedby` too, so it is read before the user trips an error rather
+     * than only after.
+     */
+    infoMessage?: string | null;
+    /**
+     * Marks the card invalid without supplying a message, for a consumer driving
+     * validity from a server or its own rules.
+     */
+    invalid?: boolean;
+    /**
+     * Submits the card under this name when it sits inside (or is associated with)
+     * a form. Omitted entirely when absent, unselected or disabled, which is what
+     * a native checkbox or radio does.
+     *
+     * In `radio` mode a name also GROUPS the cards that share it: selecting one
+     * deselects the rest, and Arrow/Home/End move the selection between them under
+     * a single tab stop, the way a native radio group behaves. Grouping is scoped
+     * to cards sharing a root node, so two forms on one page can both use
+     * `name="plan"` without interfering. Leave `name` off and each card stays the
+     * independent toggle it was before this prop existed.
+     */
+    name?: string;
+    /** Value submitted while selected. Defaults to `'on'`, the native default. */
+    value?: string;
+    /**
+     * Makes an unselected card block submission. In a named `radio` group this is
+     * the native "pick one" rule over the whole group. Invalid validation moves
+     * focus to the visible card, since the form control behind it is deliberately
+     * not a tab stop.
+     */
+    required?: boolean;
+    /**
+     * `id` of a form elsewhere in the same document, for a card rendered outside
+     * it. Custom elements have no form association through this prop: inside
+     * `<sui-choicebox>` the control lives in a shadow root and cannot reach a form
+     * in the host document, which is what `ElementInternals` handles there
+     * instead.
+     */
+    form?: string;
 };
 export type ChoiceboxEventProperties = {
     onclick?: (selected: boolean) => void;

package/dist/ColorPicker/ColorPicker.svelte

@@ -1,4 +1,6 @@
 <script lang="ts">
+  import { registerDismissible } from '../_interaction/dismissal';
+  import { describeField } from '../_field/description';
   import Button from '../Button/Button.svelte';
   import Input from '../Input/Input.svelte';
   import Slider from '../Slider/Slider.svelte';
@@ -24,13 +26,35 @@
     testId,
     onchange,
     oninput,
-    classes
+    classes,
+    errorMessage,
+    infoMessage,
+    invalid = false
   }: ColorPickerProperties = $props();
 
+  /* The control and the text that explains it were never linked: a screen-reader
+     user reaching the swatch heard "Pick a color" and nothing about why the last
+     one was rejected. `describeField` composes the reference from the messages
+     that are actually rendered, so aria-describedby never points at an id that is
+     not in the DOM -- which passes an attribute assertion and resolves to nothing
+     in a real reader.
+
+     It describes the group holding the swatch button and the hex field, because
+     the message is about the colour rather than about either control, and because
+     neither `Button` nor `Input` exposes an `aria-describedby` seam to bind it to
+     one of them. The role is conditional so a ColorPicker with no messages keeps
+     the accessibility tree it had before these props existed. */
+  const fieldUid = $props.id();
+  const field = $derived(
+    describeField(fieldUid, { error: errorMessage, info: infoMessage, invalid })
+  );
+  const describedGroup = $derived(field.describedBy !== null || field.ariaInvalid !== null);
+
   // ── Internal state ──────────────────────────────────────────────
 
   let open = $state(false);
   let containerEl: HTMLDivElement | null = $state(null);
+  let triggerWrapEl: HTMLDivElement | null = $state(null);
 
   let hue = $state(0);
   let sat = $state(1);
@@ -46,21 +70,43 @@
   let currentRgb = $derived(hsvToRgb(hue, sat, val));
   let currentHsl = $derived(hsvToHsl(hue, sat, val));
 
-  let _syncTrigger = $derived.by(() => {
+  // The hex string this component itself last wrote to `value` via commitColor.
+  // Plain (non-`$state`) bookkeeping -- like Tabs' `lastSelectionKey` -- so reading
+  // it never creates a reactive dependency; only `value` needs to.
+  let lastCommittedHex: string | null = null;
+
+  // Keeps hue/sat/val honest against `value` for every route that is NOT
+  // commitColor -- an externally-changed `value` prop, or the popover's own hex
+  // field/trigger input, which write `value` directly. `{@attach}` runs its
+  // callback inside a real reactive effect (see attachments.js), so reading
+  // `value` here re-runs it on change without reaching for the banned $effect.
+  // Skipped entirely when `value` merely echoes our own last commit, so the
+  // hue we just set from a drag never gets round-tripped back through hex.
+  function syncFromValue(_node: HTMLDivElement): void {
+    if (value === lastCommittedHex) {
+      return;
+    }
     const hsv = hexToHsv(value);
-    if (hsv !== null) {
+    if (hsv === null) {
+      return;
+    }
+    sat = hsv.s;
+    val = hsv.v;
+    // A grey hex (sat 0, from d === 0) has no recoverable hue -- rgbToHsv defaults
+    // it to 0, which is not "the" hue, just an artifact of the formula. Leaving
+    // `hue` alone here is what keeps a drag down to grey from snapping the hue
+    // slider to red.
+    if (hsv.s > 0) {
       hue = hsv.h;
-      sat = hsv.s;
-      val = hsv.v;
     }
-    return value;
-  });
+  }
 
   // ── Color commit ────────────────────────────────────────────────
 
   function commitColor() {
     const hex = hsvToHex(hue, sat, val);
     if (hex !== value) {
+      lastCommittedHex = hex;
       value = hex;
       oninput?.(value);
       onchange?.(value);
@@ -75,15 +121,29 @@
     }
   }
 
-  function handleWindowClick(e: MouseEvent) {
-    if (
-      open &&
-      containerEl !== null &&
-      e.target instanceof Node &&
-      containerEl.contains(e.target) === false
-    ) {
-      open = false;
-    }
+  // Registered for exactly the popover's open span (the {#if open} block below),
+  // same as Menu's dismissalAction, so this popover only answers Escape/outside-press
+  // while it is the topmost dismissible surface -- a picker opened inside a Modal or
+  // Sheet no longer closes the layer behind it. `element` is containerEl (the whole
+  // component, trigger included) rather than just the popover: a press on the swatch
+  // button that reopens/toggles the popover must not also be read as an outside press
+  // by the module, matching the old handleWindowClick's boundary exactly.
+  function dismissalAction(_node: HTMLDivElement) {
+    const release = registerDismissible({
+      element: () => containerEl,
+      // Wherever focus happens to be inside the popover -- the sat panel, a field,
+      // the mode-toggle button -- matching ContextMenu's "wherever focus happens to
+      // be" rule, then hands focus back to the trigger so keyboard users don't lose
+      // their place.
+      onEscape: () => {
+        open = false;
+        triggerWrapEl?.querySelector('button')?.focus();
+      },
+      onOutside: () => {
+        open = false;
+      }
+    });
+    return { destroy: release };
   }
 
   // ── Saturation panel drag ───────────────────────────────────────
@@ -123,6 +183,53 @@
     commitColor();
   }
 
+  // Small step for the arrow keys, larger step for Page Up/Down -- mirrors the
+  // native <input type="range"> convention Slider relies on.
+  const SAT_STEP = 0.01;
+  const SAT_PAGE_STEP = 0.1;
+
+  function handleSatKeydown(e: KeyboardEvent) {
+    if (disabled) {
+      return;
+    }
+    switch (e.key) {
+      case 'ArrowLeft':
+        sat = Math.max(0, sat - SAT_STEP);
+        break;
+      case 'ArrowRight':
+        sat = Math.min(1, sat + SAT_STEP);
+        break;
+      case 'ArrowUp':
+        val = Math.min(1, val + SAT_STEP);
+        break;
+      case 'ArrowDown':
+        val = Math.max(0, val - SAT_STEP);
+        break;
+      case 'PageUp':
+        // Larger step on the same axis Home/End jump on -- see below.
+        sat = Math.min(1, sat + SAT_PAGE_STEP);
+        break;
+      case 'PageDown':
+        sat = Math.max(0, sat - SAT_PAGE_STEP);
+        break;
+      case 'Home':
+        // Home/End follow the ARIA slider contract for "the" value this role
+        // formally exposes -- aria-valuenow/min/max track saturation, so that
+        // is the axis being adjusted here. Brightness is left untouched, same
+        // as arrow keys never touch the axis they aren't bound to.
+        sat = 0;
+        break;
+      case 'End':
+        sat = 1;
+        break;
+      default:
+        // Not one of ours -- leave it unconsumed (Tab, Enter, etc.).
+        return;
+    }
+    e.preventDefault();
+    commitColor();
+  }
+
   // ── Hue slider ─────────────────────────────────────────────────
 
   let hueDegrees = $derived(Math.round(hue * 360));
@@ -182,14 +289,17 @@
   }
 </script>
 
-<svelte:window onclick={handleWindowClick} />
-
 <div
   class="color-picker-container {classes ?? ''}"
   class:disabled
+  role={describedGroup ? 'group' : null}
+  aria-label={describedGroup && typeof label === 'string' ? label : null}
+  aria-describedby={field.describedBy}
+  aria-invalid={field.ariaInvalid}
   data-pw={testId}
   testID={testId}
   bind:this={containerEl}
+  {@attach syncFromValue}
 >
   {#if typeof label === 'string'}
     <span class="color-picker-label">{label}</span>
@@ -197,7 +307,11 @@
 
   <!-- Trigger: swatch button + optional hex input -->
   <div class="color-picker-row">
-    <div class="color-picker-swatch-btn" class:standalone={showValue === false}>
+    <div
+      class="color-picker-swatch-btn"
+      class:standalone={showValue === false}
+      bind:this={triggerWrapEl}
+    >
       <Button onclick={togglePicker} {disabled} ariaLabel="Pick a color" ariaExpanded={open}>
         <span class="color-picker-checkerboard">
           <span class="color-picker-swatch" style="background-color: {value};"></span>
@@ -219,7 +333,7 @@
 
   <!-- Popover panel -->
   {#if open}
-    <div class="color-picker-popover" role="dialog" aria-label="Color picker">
+    <div class="color-picker-popover" role="dialog" aria-label="Color picker" use:dismissalAction>
       <div
         class="cp-sat-panel"
         style="background-color: {hsvToHex(hue, 1, 1)};"
@@ -227,6 +341,7 @@
         onpointerdown={handleSatDown}
         onpointermove={handleSatMove}
         onpointerup={handleSatUp}
+        onkeydown={handleSatKeydown}
         role="slider"
         aria-label="Saturation and brightness"
         aria-valuenow={Math.round(sat * 100)}
@@ -303,7 +418,41 @@
   {/if}
 </div>
 
+{#if field.showsError}
+  <div
+    id={field.errorId}
+    role="alert"
+    class="field-error"
+    data-pw={typeof testId === 'string' ? `${testId}-error-message` : null}
+    testID={typeof testId === 'string' ? `${testId}-error-message` : null}
+  >
+    {errorMessage}
+  </div>
+{/if}
+{#if field.showsInfo}
+  <div
+    id={field.infoId}
+    class="field-info"
+    data-pw={typeof testId === 'string' ? `${testId}-info-message` : null}
+    testID={typeof testId === 'string' ? `${testId}-info-message` : null}
+  >
+    {infoMessage}
+  </div>
+{/if}
+
 <style>
+  .field-error {
+    color: var(--field-error-color, #c5120a);
+    font-size: var(--field-error-font-size, 12px);
+    margin: var(--field-error-margin, 4px 0 0 0);
+  }
+
+  .field-info {
+    color: var(--field-info-color, #6b7280);
+    font-size: var(--field-info-font-size, 12px);
+    margin: var(--field-info-margin, 4px 0 0 0);
+  }
+
   /* ── Container ─────────────────────────────────────────────── */
 
   .color-picker-container {

package/dist/ColorPicker/properties.d.ts

@@ -8,6 +8,22 @@ export type OptionalColorPickerProperties = {
     showValue?: boolean;
     testId?: string;
     classes?: string;
+    /**
+     * Text shown, and announced, when the chosen colour is in error ("not enough
+     * contrast on white"). Referenced by `aria-describedby` on the group holding
+     * the swatch and the hex field, and sets `aria-invalid` while present.
+     */
+    errorMessage?: string | null;
+    /**
+     * Persistent helper text describing the control. Referenced the same way, so
+     * it is read before the user trips an error rather than only after.
+     */
+    infoMessage?: string | null;
+    /**
+     * Marks the control invalid without supplying a message, for a consumer
+     * driving validity from a server or its own rules.
+     */
+    invalid?: boolean;
 };
 export type ColorPickerEventProperties = {
     onchange?: (value: string) => void;

package/dist/Combobox/Combobox.svelte

@@ -1,5 +1,7 @@
 <script lang="ts">
-  import { onMount, tick } from 'svelte';
+  import { registerDismissible } from '../_interaction/dismissal';
+  import { describeField } from '../_field/description';
+  import { tick } from 'svelte';
   import Input from '../Input/Input.svelte';
   import Pill from '../Pill/Pill.svelte';
   import type { ComboboxItem, ComboboxProperties } from './properties';
@@ -50,9 +52,32 @@
     onchange,
     onadd,
     onremove,
-    oncreate
+    oncreate,
+    errorMessage,
+    infoMessage,
+    invalid = false
   }: ComboboxProperties = $props();
 
+  /* The control and the text that explains it were never linked: a screen-reader
+     user reaching this combobox heard its name and nothing about why the value
+     was rejected. `describeField` composes the reference from the messages that
+     are actually rendered, so aria-describedby never points at an id that is not
+     in the DOM -- which passes an attribute assertion and resolves to nothing in
+     a real reader.
+
+     It goes on a group around the control rather than on the `role="combobox"`
+     element itself, because that element is inside `Input` and `Input` exposes
+     no `aria-describedby` seam -- it derives its own from the messages IT is
+     given, which are a different pair of props. Per-control is the stronger
+     placement and needs that seam; see docs/Combobox.md. The role is conditional
+     so a Combobox with no messages keeps the accessibility tree it had before
+     these props existed. */
+  const fieldUid = $props.id();
+  const field = $derived(
+    describeField(fieldUid, { error: errorMessage, info: infoMessage, invalid })
+  );
+  const describedGroup = $derived(field.describedBy !== null || field.ariaInvalid !== null);
+
   let containerEl: HTMLDivElement | null = $state(null);
   let inputRef: ReturnType<typeof Input> | null = $state(null);
 
@@ -295,12 +320,6 @@
           removeValue(selected[selected.length - 1]);
         }
         break;
-      case 'Escape':
-        if (open) {
-          event.preventDefault();
-          closeDropdown();
-        }
-        break;
       case 'Tab':
         if (open) {
           closeDropdown();
@@ -327,28 +346,30 @@
     }
   }
 
-  function handleClickOutside(event: Event) {
-    if (
-      event.target instanceof Node &&
-      containerEl !== null &&
-      !containerEl.contains(event.target)
-    ) {
-      closeDropdown();
-    }
+  // Registered for exactly the dropdown's open span (the `{#if open && !disabled}`
+  // block below), same as Menu's dismissalAction, so this dropdown only answers
+  // Escape/outside-press while it is the topmost dismissible surface -- a combobox
+  // opened inside a Modal, Sheet, Menu, ContextMenu or CommandMenu no longer closes
+  // the layer behind it. Unlike Select's dropdown, this one is never portaled --
+  // it is always a DOM descendant of containerEl -- so containerEl alone is enough
+  // for the module's own inside/outside test; no second hit-test is needed here.
+  function dismissalAction(_node: HTMLDivElement) {
+    const release = registerDismissible({
+      element: () => containerEl,
+      onOutside: closeDropdown,
+      onEscape: closeDropdown
+    });
+    return { destroy: release };
   }
-
-  onMount(() => {
-    document.addEventListener('click', handleClickOutside);
-    return () => {
-      document.removeEventListener('click', handleClickOutside);
-    };
-  });
 </script>
 
 <div
   class="combobox {classes ?? ''}"
   class:disabled
   bind:this={containerEl}
+  role={describedGroup ? 'group' : null}
+  aria-describedby={field.describedBy}
+  aria-invalid={field.ariaInvalid}
   data-pw={testId}
   testID={testId}
 >
@@ -394,7 +415,13 @@
   </div>
 
   {#if open && !disabled}
-    <div class="combobox-dropdown" role="listbox" id={listboxId} aria-label={ariaLabel}>
+    <div
+      class="combobox-dropdown"
+      role="listbox"
+      id={listboxId}
+      aria-label={ariaLabel}
+      use:dismissalAction
+    >
       {#if typeof dropdownHeader === 'function'}
         <div class="combobox-dropdown-header">{@render dropdownHeader()}</div>
       {/if}
@@ -498,7 +525,41 @@
   {/if}
 </div>
 
+{#if field.showsError}
+  <div
+    id={field.errorId}
+    role="alert"
+    class="field-error"
+    data-pw={typeof testId === 'string' ? `${testId}-error-message` : null}
+    testID={typeof testId === 'string' ? `${testId}-error-message` : null}
+  >
+    {errorMessage}
+  </div>
+{/if}
+{#if field.showsInfo}
+  <div
+    id={field.infoId}
+    class="field-info"
+    data-pw={typeof testId === 'string' ? `${testId}-info-message` : null}
+    testID={typeof testId === 'string' ? `${testId}-info-message` : null}
+  >
+    {infoMessage}
+  </div>
+{/if}
+
 <style>
+  .field-error {
+    color: var(--field-error-color, #c5120a);
+    font-size: var(--field-error-font-size, 12px);
+    margin: var(--field-error-margin, 4px 0 0 0);
+  }
+
+  .field-info {
+    color: var(--field-info-color, #6b7280);
+    font-size: var(--field-info-font-size, 12px);
+    margin: var(--field-info-margin, 4px 0 0 0);
+  }
+
   .combobox {
     position: relative;
     width: var(--combobox-width, 100%);
@@ -605,7 +666,8 @@
     font-size: var(--combobox-option-font-size, inherit);
     font-weight: var(--combobox-option-font-weight, inherit);
     cursor: pointer;
-    transition: background 0.1s;
+    transition: background var(--combobox-option-transition-duration, var(--motion-duration, 0.1s))
+      var(--combobox-option-transition-easing, var(--motion-easing, ease));
   }
 
   .combobox-option:hover,

package/dist/Combobox/properties.d.ts

@@ -58,6 +58,29 @@ export type OptionalComboboxProperties = {
     action?: ComboboxAction;
     /** Custom leading icon for the persistent action row. */
     actionIcon?: Snippet;
+    /**
+     * Text shown, and announced, when the control is in error. Referenced by
+     * `aria-describedby` on a group wrapping the control, and sets `aria-invalid`
+     * while present.
+     *
+     * Placed on the group rather than on the `role="combobox"` element itself:
+     * that element is rendered by `Input`, which derives its own description from
+     * its own `onErrorMessage` / `infoMessage` props and exposes no seam for an
+     * outside one. A group description is announced on entering the group rather
+     * than on the control, which is weaker; pass `inputProperties.onErrorMessage`
+     * instead when you want the message bound to the text field itself.
+     */
+    errorMessage?: string | null;
+    /**
+     * Persistent helper text describing the control. Referenced the same way, so
+     * it is read before the user trips an error rather than only after.
+     */
+    infoMessage?: string | null;
+    /**
+     * Marks the control invalid without supplying a message, for a consumer
+     * driving validity from a server or its own rules.
+     */
+    invalid?: boolean;
 };
 export type ComboboxEventProperties = {
     onselect?: (item: ComboboxItem) => void;