@juspay/svelte-ui-components 4.27.5 → 4.28.0

package/dist/Checkbox/Checkbox.svelte

@@ -1,5 +1,6 @@
 <script lang="ts">
   import { flushSync } from 'svelte';
+  import { describeField } from '../_field/description';
   import type { CheckboxProperties } from './properties';
   import checkmarkSvg from '../assets/checkmark.svg?raw';
   import minusSvg from '../assets/minus.svg?raw';
@@ -19,9 +20,37 @@
     controlled = false,
     attributes,
     name,
-    value
+    value,
+    required = false,
+    form,
+    errorMessage,
+    infoMessage,
+    invalid = false
   }: CheckboxProperties = $props();
 
+  /* The control and the text that explains it were never linked: a screen-reader
+     user reaching this control heard its name and nothing about why it 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. */
+  const fieldUid = $props.id();
+  const field = $derived(
+    describeField(fieldUid, { error: errorMessage, info: infoMessage, invalid })
+  );
+
+  // A mixed box submits nothing and satisfies nothing, so the control behind it is
+  // unchecked while `indeterminate` holds — the native property, not a third state.
+  const submitsChecked: boolean = $derived(indeterminate ? false : checked);
+  const boxState: 'checked' | 'unchecked' | 'indeterminate' = $derived(
+    indeterminate ? 'indeterminate' : checked ? 'checked' : 'unchecked'
+  );
+
+  let box: HTMLSpanElement | null = $state(null);
+  // Release's own ref, kept: the native input is aria-hidden, tabindex="-1" and
+  // pointer-events: none -- a form-submission mirror that never receives a real
+  // click, so the browser never fires `change` on it either. handleClick
+  // dispatches input/change manually through this ref.
   let nativeInputEl: HTMLInputElement | null = $state(null);
 
   // Visible text wins over `ariaLabel`, which is what `properties.ts` has always
@@ -90,6 +119,14 @@
     nativeInputEl?.dispatchEvent(new Event('change', { bubbles: true, composed: true }));
   }
 
+  // The form control is `tabindex="-1"`, so the browser's own "focus the invalid
+  // field" step would land on an element the user cannot see or reach. Focus the
+  // box that carries the role instead.
+  function handleInvalid(e: Event): void {
+    e.preventDefault();
+    box?.focus();
+  }
+
   function handleKeyDown(e: KeyboardEvent): void {
     if (e.key === ' ' || e.key === 'Enter') {
       e.preventDefault();
@@ -117,10 +154,14 @@
   <input
     type="checkbox"
     class="native-checkbox"
-    {checked}
+    checked={submitsChecked}
+    {indeterminate}
     {disabled}
-    name={name ?? null}
     value={value ?? null}
+    {required}
+    name={typeof name === 'string' ? name : null}
+    form={typeof form === 'string' ? form : null}
+    oninvalid={handleInvalid}
     tabindex={-1}
     aria-hidden="true"
     onclick={(e: MouseEvent) => e.stopPropagation()}
@@ -129,10 +170,16 @@
     testID={typeof testId === 'string' ? `${testId}-native-input` : null}
   />
   <span
+    bind:this={box}
     class="box"
     class:checked
     class:indeterminate
     role="checkbox"
+    aria-describedby={field.describedBy}
+    aria-invalid={field.ariaInvalid}
+    data-state={boxState}
+    data-disabled={disabled ? '' : null}
+    aria-required={required ? 'true' : null}
     tabindex={disabled ? -1 : 0}
     aria-checked={indeterminate ? 'mixed' : checked}
     aria-disabled={disabled}
@@ -163,6 +210,28 @@
   <span class="label" hidden={text.length === 0}>{text}</span>
 </label>
 
+{#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>
   .container {
     display: var(--checkbox-container-display, inline-flex);
@@ -241,4 +310,16 @@
     font-weight: var(--checkbox-label-font-weight, 400);
     color: var(--checkbox-label-color, #212121);
   }
+
+  .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);
+  }
 </style>

package/dist/Checkbox/properties.d.ts

@@ -4,12 +4,37 @@ export type MandatoryCheckboxProperties = {
     text?: string;
 };
 export type OptionalCheckboxProperties = {
-    /** Visible label. Optional, defaulting to `''` (unlabelled) -- matching Toggle's
-     *  own `text` contract (Toggle/properties.ts) -- so a form-only checkbox
-     *  (`<Checkbox name="agree" />`) does not need an empty string just to compile.
-     *  A checkbox with no visible text needs `ariaLabel` for an accessible name;
-     *  see `ariaLabel` below. */
+    /**
+     * Visible label. Optional, and empty by default -- matching Toggle's own `text`
+     * contract (Toggle/properties.ts) -- so a form-only checkbox
+     * (`<Checkbox name="agree" />`) does not need an empty string just to compile.
+     *
+     * It mattered beyond the type. `Checkbox` dereferences `text.length`, and the
+     * custom-element build type-checks nothing, so `<sui-checkbox name="terms">`
+     * with no `text` attribute threw during render and left an empty shadow root
+     * -- the same failure mode as the `attributes` collision, from a different
+     * cause. `Toggle` and `Radio` already declared it optional with a default.
+     *
+     * A checkbox with no visible text needs `ariaLabel` for an accessible name;
+     * see `ariaLabel` below.
+     */
     text?: string;
+    /**
+     * Text shown, and announced, when the control is in error. Linked to the
+     * control through `aria-describedby`, and sets `aria-invalid` while present.
+     */
+    errorMessage?: string | null;
+    /**
+     * Persistent helper text describing the control. Linked through
+     * `aria-describedby` too, 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;
     checked?: boolean;
     disabled?: boolean;
     indeterminate?: boolean;
@@ -33,16 +58,23 @@ export type OptionalCheckboxProperties = {
      *  `aria-controls` to point at, or a consumer's own test attribute. Spread
      *  last, so a value here wins over the component's own `data-pw`. */
     attributes?: Record<string, string>;
-    /** Native `name` on the underlying `<input type="checkbox">`, so the control
-     *  participates in a surrounding `<form>`'s submission. Omitted by default:
-     *  the input stays nameless and outside `FormData`, exactly as before this
-     *  prop existed. */
+    /** Submits the box under this name when it sits inside (or is associated with) a
+     *  form. Omitted by default: with no `name` the box stays outside `FormData`,
+     *  exactly as before this prop existed. Omitted from submission too when unchecked,
+     *  indeterminate or disabled, which is what a native `<input type="checkbox">` does. */
     name?: string;
-    /** Native `value` submitted when checked. Defaults to `"on"` — the native
-     *  checkbox default — when omitted, so setting `name` alone is enough to
-     *  form-associate a plain "checked or not" checkbox. An unchecked checkbox
-     *  never appears in `FormData`, matching native behaviour. */
+    /** Value submitted while checked. Left unset, the attribute is omitted and the native
+     *  checkbox's own `"on"` default is what submits -- so setting `name` alone is enough to
+     *  form-associate a plain "checked or not" box, and an existing consumer's DOM is
+     *  unchanged. The default is the platform's, not one this component hardcodes. */
     value?: string;
+    /** Makes an unchecked box block submission. Invalid validation moves focus to the
+     *  visible box, 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 box rendered outside it.
+     *  Custom elements have no form association: inside `<sui-checkbox>` the control
+     *  lives in a shadow root and cannot reach a form in the host document. */
+    form?: string;
 };
 export type CheckboxEventProperties = {
     onclick?: (checked: boolean) => void;

package/dist/ChipInput/ChipInput.svelte

@@ -1,4 +1,5 @@
 <script lang="ts">
+  import { describeField } from '../_field/description';
   import Input from '../Input/Input.svelte';
   import Pill from '../Pill/Pill.svelte';
   import type { ChipInputProperties } from './properties';
@@ -11,12 +12,33 @@
     editable = false,
     testId,
     classes,
+    errorMessage,
+    infoMessage,
+    invalid = false,
     onadd,
     ondismiss,
     onedit,
     onchange
   }: ChipInputProperties = $props();
 
+  /* The widget and the text that explains it were never linked: a screen-reader
+     user heard the draft field's name and nothing about why the last 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 describes the GROUP rather than the draft field, because that is what the
+     message is about: "at most five tags" is a fact about the collection, not
+     about the box the next one is typed into. The role is conditional so a
+     ChipInput with no messages keeps the accessibility tree it had before this
+     prop existed -- an unnamed, undescribed group is announced noise. */
+  const fieldUid = $props.id();
+  const field = $derived(
+    describeField(fieldUid, { error: errorMessage, info: infoMessage, invalid })
+  );
+  const describedGroup = $derived(field.describedBy !== null || field.ariaInvalid !== null);
+
   let draft = $state('');
 
   // The chip currently swapped for an inline edit field, held by VALUE rather than by slot
@@ -131,7 +153,15 @@
   }
 </script>
 
-<div class="chip-input {classes ?? ''}" data-pw={testId} testID={testId}>
+<div
+  class="chip-input {classes ?? ''}"
+  role={describedGroup ? 'group' : null}
+  aria-label={describedGroup ? ariaLabel : null}
+  aria-describedby={field.describedBy}
+  aria-invalid={field.ariaInvalid}
+  data-pw={testId}
+  testID={testId}
+>
   {#each values as chip, index (chip)}
     {#if editable && editingChip === chip && !disabled}
       <div class="chip-input-edit-wrap">
@@ -186,7 +216,41 @@
   </div>
 </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);
+  }
+
   .chip-input {
     display: flex;
     flex-wrap: var(--chip-input-flex-wrap, wrap);
@@ -209,8 +273,11 @@
        Tokens the component owns STRUCTURALLY — the draft field's inline padding, margin and
        shadow, and its width/height — deliberately stay fixed, since those position the field among
        the chips rather than describe how it looks. */
-    --chip-input-pill-background-default: var(--pill-background, #e0e0e0);
-    --chip-input-pill-color-default: var(--pill-color, #333333);
+    --chip-input-pill-background-default: var(
+      --pill-background,
+      var(--pill-tone-neutral-background, #e0e0e0)
+    );
+    --chip-input-pill-color-default: var(--pill-color, var(--pill-tone-neutral-color, #333333));
     --chip-input-pill-dismiss-color-default: var(--pill-dismiss-color, currentColor);
     --chip-input-pill-font-size-default: var(--pill-font-size, 13px);
     --chip-input-pill-font-weight-default: var(--pill-font-weight, 500);

package/dist/ChipInput/properties.d.ts

@@ -31,6 +31,22 @@ export type OptionalChipInputProperties = {
     editable?: boolean;
     testId?: string;
     classes?: string;
+    /**
+     * Text shown, and announced, when the chip collection is in error ("at most
+     * five tags"). Referenced by `aria-describedby` on the group wrapping the
+     * chips and the draft field, and sets `aria-invalid` while present.
+     */
+    errorMessage?: string | null;
+    /**
+     * Persistent helper text describing the whole 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 ChipInputEventProperties = {
     onadd?: (value: string) => void;

package/dist/Choicebox/Choicebox.svelte

@@ -1,4 +1,6 @@
 <script lang="ts">
+  import { describeField } from '../_field/description';
+  import { joinChoiceboxGroup, moveWithinChoiceboxGroup, selectExclusively } from './group';
   import type { ChoiceboxProperties } from './properties';
   import checkmarkSvg from '../assets/checkmark.svg?raw';
 
@@ -10,9 +12,58 @@
     showIndicator = true,
     testId,
     onclick,
-    classes
+    classes,
+    errorMessage,
+    infoMessage,
+    invalid = false,
+    name,
+    value = 'on',
+    required = false,
+    form
   }: ChoiceboxProperties = $props();
 
+  /* The card and the text that explains it were never linked: a screen-reader
+     user reaching this control heard its name and nothing about why it 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. */
+  const fieldUid = $props.id();
+  const field = $derived(
+    describeField(fieldUid, { error: errorMessage, info: infoMessage, invalid })
+  );
+
+  /* Grouping is opt-in through `name`, so every card written before this prop
+     existed keeps behaving as an independent toggle. */
+  const groupKey = $derived(
+    mode === 'radio' && typeof name === 'string' && name !== '' ? name : null
+  );
+
+  let card: HTMLDivElement | null = $state(null);
+
+  /* Registers the card with its group and re-registers whenever an input the
+     group's single tab stop depends on changes. `selected` and `disabled` are
+     read HERE rather than only inside the callbacks: a closure reading them
+     later creates no dependency, and the tab stop has to move when a SIBLING's
+     selection changes, which no per-instance `$derived` can observe. */
+  function groupMembership(node: HTMLElement) {
+    const key = groupKey;
+    if (key === null) {
+      return;
+    }
+    const selectedNow = selected;
+    const disabledNow = disabled;
+    return joinChoiceboxGroup(key, {
+      element: node,
+      isSelected: () => selectedNow,
+      isDisabled: () => disabledNow,
+      setSelected: (next: boolean) => {
+        selected = next;
+      },
+      notify: (next: boolean) => onclick?.(next)
+    });
+  }
+
   function handleClick(): void {
     if (disabled) {
       return;
@@ -20,32 +71,93 @@
     if (mode === 'radio' && selected) {
       return;
     }
+    if (groupKey !== null && card !== null) {
+      // The group owns the exclusivity a native radio gets from the browser:
+      // selecting here deselects the siblings and tells each of them.
+      selectExclusively(card);
+      onclick?.(true);
+      return;
+    }
     selected = !selected;
     onclick?.(selected);
   }
 
+  // The form control is `tabindex="-1"`, so the browser's own "focus the invalid
+  // field" step would land on an element the user cannot see or reach. Focus the
+  // card that carries the role instead.
+  function handleInvalid(e: Event): void {
+    e.preventDefault();
+    card?.focus();
+  }
+
   function handleKeyDown(e: KeyboardEvent): void {
     if (e.key === ' ' || e.key === 'Enter') {
       e.preventDefault();
       handleClick();
+      return;
+    }
+    if (groupKey === null || disabled || card === null) {
+      return;
+    }
+    // Both axes, because a group of cards may be laid out as a row or a column
+    // and the user cannot tell which the author chose.
+    const step =
+      e.key === 'ArrowDown' || e.key === 'ArrowRight'
+        ? 'next'
+        : e.key === 'ArrowUp' || e.key === 'ArrowLeft'
+          ? 'previous'
+          : e.key === 'Home'
+            ? 'first'
+            : e.key === 'End'
+              ? 'last'
+              : null;
+    if (step === null) {
+      return;
+    }
+    if (moveWithinChoiceboxGroup(card, step)) {
+      e.preventDefault();
     }
   }
 </script>
 
 <!-- svelte-ignore a11y_no_noninteractive_tabindex -->
+<!-- `tabindex` is the ungrouped answer and the server-rendered baseline. A named
+     radio group has ONE tab stop rather than one per card, which depends on
+     every sibling's state and so is applied by `groupMembership` once the group
+     exists on the client. -->
 <div
+  bind:this={card}
   class="choicebox {classes ?? ''}"
   class:selected
   class:disabled
   role={mode === 'radio' ? 'radio' : 'checkbox'}
   aria-checked={selected}
   aria-disabled={disabled}
+  aria-required={required ? 'true' : null}
+  aria-describedby={field.describedBy}
+  aria-invalid={field.ariaInvalid}
   tabindex={disabled ? -1 : 0}
   onclick={handleClick}
   onkeydown={handleKeyDown}
   data-pw={testId}
   testID={testId}
+  {@attach groupMembership}
 >
+  <input
+    type={mode === 'radio' ? 'radio' : 'checkbox'}
+    class="native-control"
+    checked={selected}
+    {disabled}
+    {value}
+    {required}
+    name={typeof name === 'string' ? name : null}
+    form={typeof form === 'string' ? form : null}
+    oninvalid={handleInvalid}
+    tabindex={-1}
+    aria-hidden="true"
+    data-pw={typeof testId === 'string' ? `${testId}-native-input` : null}
+    testID={typeof testId === 'string' ? `${testId}-native-input` : null}
+  />
   {#if typeof children === 'function'}
     {@render children()}
   {/if}
@@ -59,7 +171,50 @@
   {/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>
+  .native-control {
+    position: absolute;
+    opacity: 0;
+    width: 0;
+    height: 0;
+    margin: 0;
+    pointer-events: none;
+  }
+
+  .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);
+  }
+
   .choicebox {
     display: var(--choicebox-display, flex);
     align-items: var(--choicebox-align-items, center);

package/dist/Choicebox/group.d.ts

@@ -0,0 +1,63 @@
+/**
+ * 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.
+ */
+export type ChoiceboxGroupMember = {
+    readonly element: HTMLElement;
+    /**
+     * Snapshots taken when the member registered, NOT live reads: Choicebox
+     * re-registers whenever either value changes, and that re-registration is what
+     * recalculates the group. So a `refreshRoving` running in the same tick as a
+     * `setSelected` sees the pre-change answer and is corrected a moment later by
+     * the re-registration it caused.
+     */
+    readonly isSelected: () => boolean;
+    readonly isDisabled: () => boolean;
+    /** Writes the member's own bindable `selected` prop. */
+    readonly setSelected: (next: boolean) => void;
+    /** Fires the member's `onclick`, so a group move reports like a click. */
+    readonly notify: (next: boolean) => void;
+};
+/**
+ * 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 declare function joinChoiceboxGroup(name: string, member: ChoiceboxGroupMember): () => void;
+/**
+ * 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 declare function selectExclusively(element: HTMLElement): void;
+export type GroupStep = 'next' | 'previous' | 'first' | 'last';
+/**
+ * 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 declare function moveWithinChoiceboxGroup(element: HTMLElement, step: GroupStep): boolean;