@juspay/svelte-ui-components 4.51.0 → 4.52.0

package/dist/SplitInput/field-name.js

@@ -0,0 +1,50 @@
+const nonEmpty = (text) => {
+    const trimmed = typeof text === 'string' ? text.trim() : '';
+    return trimmed === '' ? null : trimmed;
+};
+const capitalise = (text) => text.charAt(0).toUpperCase() + text.slice(1);
+/**
+ * What one box holds, so the position reads as the user experiences it: the boxes
+ * of a PIN or one-time code are "digit 2 of 6", the boxes of a free-text code are
+ * "character 2 of 6", and anything wider than one character ("192", an area code)
+ * is just a "field" -- calling a three-digit octet a digit would be wrong.
+ */
+const unitFor = (config) => {
+    if (config.maxLength !== 1) {
+        return 'field';
+    }
+    return config.dataType === 'tel' || config.dataType === 'number' ? 'digit' : 'character';
+};
+/** Capitalised only when nothing precedes it: after "One-time code," it stays lower-case. */
+const defaultPosition = (config, index, total, leading) => {
+    const text = `${unitFor(config)} ${index + 1} of ${total}`;
+    return leading ? capitalise(text) : text;
+};
+/**
+ * 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 const resolveFieldName = ({ index, total, config, groupLabel, positionLabel }) => {
+    const explicit = nonEmpty(config.ariaLabel);
+    if (explicit !== null) {
+        return explicit;
+    }
+    const group = nonEmpty(groupLabel);
+    const own = nonEmpty(config.label) ??
+        nonEmpty(positionLabel?.(index + 1, total)) ??
+        defaultPosition(config, index, total, group === null);
+    return group === null ? own : `${group}, ${own}`;
+};

package/dist/SplitInput/properties.d.ts

@@ -1,5 +1,5 @@
 import type { OptionalInputProperties } from '../Input/properties';
-export type FieldConfig = Pick<OptionalInputProperties, 'dataType' | 'maxLength' | 'min' | 'max' | 'placeholder' | 'validationPattern' | 'validators' | 'label' | 'autoComplete' | 'inputMode' | 'testId'>;
+export type FieldConfig = Pick<OptionalInputProperties, 'dataType' | 'maxLength' | 'min' | 'max' | 'placeholder' | 'validationPattern' | 'validators' | 'label' | 'autoComplete' | 'inputMode' | 'testId' | 'ariaLabel'>;
 export type SplitInputProperties = MandatorySplitInputProperties & OptionalSplitInputProperties & SplitInputEventProperties;
 export type MandatorySplitInputProperties = {
     values: string[];
@@ -13,11 +13,25 @@ export type OptionalSplitInputProperties = {
     testId?: string;
     classes?: string;
     /**
-     * Names the whole group ("One-time code"). The boxes are individually
-     * meaningless, so without this a screen-reader user reaches four unlabelled
-     * fields; naming the group is what makes them one control.
+     * Names the whole group ("One-time code"), and leads the name of every box in
+     * it ("One-time code, digit 2 of 6"), so each box is identifiable on its own --
+     * a screen reader's form-field list shows controls without their group. The
+     * boxes are individually meaningless, so naming the group is what makes them
+     * one control; leave it off and each box is named by its position alone
+     * ("Digit 2 of 6"), which says where it is but not what it is for.
+     *
+     * To name one box instead, set `ariaLabel` on its `fields` entry.
      */
     ariaLabel?: string;
+    /**
+     * Builds the position part of a box's accessible name from its 1-based
+     * position and the number of boxes. Replaces the English default ("digit 2 of
+     * 6" for single-digit boxes, "character 2 of 6" for single-character ones,
+     * "field 2 of 4" for wider boxes), so it is the hook for another language or
+     * a better noun ("octet 2 of 4"). A box with its own `ariaLabel` or visible
+     * `label` is named by that instead and never asks for a position.
+     */
+    positionLabel?: (position: number, total: number) => string;
     /**
      * Text shown, and announced, when the assembled value is in error ("That code
      * is not right"). Referenced by `aria-describedby` on the group rather than on

package/dist/Status/Status.svelte

@@ -4,18 +4,24 @@
   import Img from '../Img/Img.svelte';
 
   /**
-   * The documented default, kept as the default so this is not a breaking
-   * change. It is a relative URL resolved against whatever page renders the
-   * component, and the library ships no such file, so it only ever pointed at
-   * something real for an app serving that exact path at its own root -- and
-   * resolved to `<route>/icons/order-success-icon.svg` anywhere deeper.
+   * What `statusIcon` used to default to. It is a relative URL resolved against
+   * whatever page renders the component, and the library ships no such file, so
+   * it only ever pointed at something real for an app serving that exact path at
+   * its own root -- and resolved to `<route>/icons/order-success-icon.svg`
+   * anywhere deeper, where every card using the default made a request that
+   * 404ed before the fallback below rendered.
+   *
+   * It is no longer the default: an omitted `statusIcon` renders the built-in
+   * icon directly, with no request. The string is kept only so a consumer who
+   * spells it out themselves keeps the fallback they already had.
    */
   const LEGACY_DEFAULT_STATUS_ICON = 'icons/order-success-icon.svg';
 
   /**
-   * Stands in when the legacy default cannot be fetched, so an app that does
-   * host that path keeps getting its own file and every other app stops
-   * rendering a broken image.
+   * The default icon, inlined so it needs no request and no packaged asset (a
+   * file would have to be resolved against the consumer's base path, the
+   * `svelte-package` output and the `<sui-*>` bundle alike). Also stands in when
+   * a consumer spells out the legacy default and it cannot be fetched.
    *
    * Carries no `role` or `aria-label` of its own. Both are in `Img`'s
    * allowlist, so a root declaring them would be copied onto the live host and
@@ -26,7 +32,7 @@
     "data:image/svg+xml,%3Csvg%20xmlns%3D'http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg'%20viewBox%3D'0%200%2048%2048'%3E%3Ccircle%20cx%3D'24'%20cy%3D'24'%20r%3D'22'%20fill%3D'%23e6f6ec'%20stroke%3D'%232e994c'%20stroke-width%3D'2'%2F%3E%3Cpath%20d%3D'M15%2024.5l6.5%206.5L33%2019.5'%20fill%3D'none'%20stroke%3D'%232e994c'%20stroke-width%3D'3.5'%20stroke-linecap%3D'round'%20stroke-linejoin%3D'round'%2F%3E%3C%2Fsvg%3E";
 
   let {
-    statusIcon = LEGACY_DEFAULT_STATUS_ICON,
+    statusIcon,
     statusIconAlt = 'status',
     statusText = '',
     statusTextTag = 'div',
@@ -40,8 +46,14 @@
     testId
   }: StatusProperties = $props();
 
-  // Scoped to the untouched default on purpose. Applying it to a caller's own
-  // icon would answer a failed failure-icon with a success checkmark.
+  // `??` rather than a parameter default: a `<sui-status>` whose `status-icon`
+  // attribute is removed hands the component `null`, which a default would pass
+  // straight to Img.
+  const resolvedStatusIcon = $derived(statusIcon ?? BUILTIN_STATUS_ICON);
+
+  // Scoped to the legacy default on purpose. Applying it to a caller's own icon
+  // would answer a failed failure-icon with a success checkmark. The built-in
+  // default needs none: it cannot fail to load.
   const statusIconFallback = $derived(
     statusIcon === LEGACY_DEFAULT_STATUS_ICON ? BUILTIN_STATUS_ICON : null
   );
@@ -57,7 +69,7 @@
       {#if icon}
         {@render icon()}
       {:else}
-        <Img inlineSvg src={statusIcon} fallback={statusIconFallback} alt={statusIconAlt} />
+        <Img inlineSvg src={resolvedStatusIcon} fallback={statusIconFallback} alt={statusIconAlt} />
       {/if}
     </div>
     <svelte:element

package/dist/Status/properties.d.ts

@@ -1,6 +1,17 @@
 import type { Snippet } from 'svelte';
 import type { ButtonProperties } from '../Button/properties';
 export type StatusProperties = StatusEventProperties & {
+    /**
+     * URL of the icon shown above the title. Omit it to get the built-in
+     * checkmark, which is inlined and costs no request.
+     *
+     * A URL you pass is used as given and never replaced when it fails to load:
+     * answering a failed failure-icon with a success checkmark would be worse
+     * than showing nothing. The one exception is the literal
+     * `'icons/order-success-icon.svg'` (the former default), which still falls
+     * back to the built-in checkmark so existing callers that spell it out are
+     * unchanged.
+     */
     statusIcon?: string;
     /**
      * Accessible name for the `statusIcon` image. Defaults to `'status'`, which

package/dist/Table/BuiltinCell.svelte

@@ -36,14 +36,19 @@
     value,
     rowIndex,
     originalIndex,
+    ariaLabel,
     usePortal = false
   }: {
     column: TableColumn;
     value: TableCellValue;
     rowIndex: number;
     originalIndex: number;
+    ariaLabel?: string;
     usePortal?: boolean;
   } = $props();
+  const fieldLabel = $derived(
+    ariaLabel?.trim() || `${column.label || column.id} for row ${originalIndex + 1}`
+  );
 
   // The td applies column.align as text-align, which flex containers ignore:
   // column-flex builtins stretch their children and row-flex builtins pack to
@@ -301,20 +306,22 @@
 {:else if column.type === 'toggle'}
   {@const data = asJsonObject(value) ?? {}}
   {@const isChecked = data.checked === true}
+  <!-- This is only an event boundary; the native Toggle input owns interaction. -->
+  <!-- svelte-ignore a11y_no_static_element_interactions -->
   <span
     class="builtin-toggle"
-    role="switch"
-    aria-checked={isChecked ? 'true' : 'false'}
-    aria-label={typeof data.ariaLabel === 'string' ? data.ariaLabel : null}
     data-pw={typeof data.testId === 'string' ? data.testId : null}
     testID={typeof data.testId === 'string' ? data.testId : null}
     onclick={stopClickPropagation}
     onkeydown={stopKeydownPropagation}
-    tabindex={-1}
   >
     <Toggle
       checked={isChecked}
       text=""
+      inputRole="switch"
+      ariaLabel={typeof data.ariaLabel === 'string' && data.ariaLabel.trim()
+        ? data.ariaLabel
+        : fieldLabel}
       onclick={(newChecked) => column.onToggle?.(rowIndex, newChecked, originalIndex)}
     />
   </span>
@@ -328,6 +335,7 @@
       onkeydown={stopKeydownPropagation}
     >
       <Select
+        ariaLabel={selectData.ariaLabel?.trim() || fieldLabel}
         items={selectData.options}
         value={selectData.selectedId ? [selectData.selectedId] : []}
         placeholder={selectData.placeholder ?? ''}
@@ -360,7 +368,7 @@
       <Input
         value={inputData.value ?? ''}
         placeholder={inputData.placeholder ?? ''}
-        ariaLabel={inputData.ariaLabel ?? null}
+        ariaLabel={inputData.ariaLabel?.trim() || fieldLabel}
         disable={inputData.disabled ?? false}
         testId={inputData.testId ?? ''}
         dataType={asInputDataType(inputData.dataType ?? null)}

package/dist/Table/BuiltinCell.svelte.d.ts

@@ -4,6 +4,7 @@ type $$ComponentProps = {
     value: TableCellValue;
     rowIndex: number;
     originalIndex: number;
+    ariaLabel?: string;
     usePortal?: boolean;
 };
 declare const BuiltinCell: import("svelte").Component<$$ComponentProps, {}, "">;

package/dist/Table/Table.svelte

@@ -6,6 +6,7 @@
     SortDirection
   } from './properties';
   import { normalizeColumns } from './normalizeColumns';
+  import { rowContextLabels, selectionControlIds } from './a11y';
   import BuiltinCell from './BuiltinCell.svelte';
   import type { JSONValue } from 'type-decoder';
   import { SvelteSet } from 'svelte/reactivity';
@@ -74,6 +75,9 @@
   // (pre-sort/pre-filter). Row refs are preserved through sort/filter/paginate,
   // so cell callbacks can hand consumers a sort-stable `originalIndex`.
   let originalIndexByRow = $derived(new Map(effectiveData.map((row, index) => [row, index])));
+  const tableUid = $props.id();
+  const selectionId = selectionControlIds(tableUid);
+  let rowLabels = $derived(rowContextLabels(effectiveData, columns));
   let effectiveSortableColumns = $derived(
     normalized ? normalized.sortableColumns : sortableColumns
   );
@@ -544,7 +548,7 @@
     rowIndex: number,
     originalIndex: number
   ): string => {
-    return cfg.getRowId ? cfg.getRowId(row, rowIndex, originalIndex) : String(rowIndex);
+    return cfg.getRowId ? cfg.getRowId(row, rowIndex, originalIndex) : String(originalIndex);
   };
 
   let internalSelectedIds = new SvelteSet<string>();
@@ -569,12 +573,9 @@
   /**
    * Stable string ID for every row in the currently visible (filtered) view.
    *
-   * Each entry is resolved by iterating `filteredTableData` and looking up the
-   * row's pre-sort position via `sortedTableData.indexOf(row)`. Using the
-   * pre-filter index as the default numeric ID keeps `String(originalIndex)`
-   * stable even when the visible set shrinks or expands as the search term
-   * changes — so a row that was "row 2" in the full set keeps ID `"2"` even
-   * when it becomes the only visible result.
+   * The callback retains its current pre-filter sorted index plus originalIndex.
+   * The default ID uses the source index, so sort/filter/page transforms do not
+   * silently transfer selection to a different record.
    *
    * The Map lookup uses object reference equality, so row objects in
    * `filteredTableData` must be the same references as those in
@@ -594,7 +595,7 @@
           originalIndexByRow.get(row) ?? stableIndex
         );
       }
-      return String(stableIndex);
+      return String(originalIndexByRow.get(row) ?? stableIndex);
     });
   });
 
@@ -718,13 +719,13 @@
   };
 
   /**
-   * Attributes for one row checkbox (`rowIndex` -1 is the header). The row id
-   * doubles as the element id the header's `aria-controls` points at; the
-   * consumer's `getRowAttributes` is spread last so its own test attribute wins.
+   * Attributes for one checkbox (`rowIndex` -1 is the header). DOM identity is
+   * separate from the consumer's selection key. Preserve other caller attributes
+   * and valid unique custom IDs, while managing unsafe/colliding IDs ourselves.
    */
   const checkboxAttributes = (rowId: string, rowIndex: number): Record<string, string> => {
     const suffix = rowIndex === -1 ? 'select-all' : `row-checkbox-${rowId}`;
-    const own: Record<string, string> = rowIndex === -1 ? {} : { id: `row-checkbox-${rowId}` };
+    const own: Record<string, string> = {};
     if (typeof testId === 'string') {
       own['data-pw'] = `${testId}-${suffix}`;
       own.testID = `${testId}-${suffix}`;
@@ -732,9 +733,36 @@
     const consumer = checkboxSelection?.getRowAttributes
       ? checkboxSelection.getRowAttributes(rowId, rowIndex)
       : {};
-    return { ...own, ...consumer };
+    return {
+      ...own,
+      ...consumer,
+      id: selectionId(rowId, rowIndex === -1, consumer.id)
+    };
   };
 
+  let headerCheckboxAttributes = $derived(checkboxAttributes('__header__', -1));
+  // Evaluate caller attributes once for each rendered control. Both the DOM and
+  // its IDREF list consume the same result, including a caller-supplied ID.
+  let renderedCheckboxAttributes = $derived.by(() => {
+    if (!checkboxSelection || checkboxSelection.enabled === false) {
+      return new Map<JSONValue[], Record<string, string>>();
+    }
+    return new Map(
+      paginatedTableData.map((row, index) => {
+        const rowIndex = index + rowIndexOffset;
+        const rowId = rowIdByRow.get(row) ?? String(originalIndexByRow.get(row) ?? rowIndex);
+        return [row, checkboxAttributes(rowId, rowIndex)];
+      })
+    );
+  });
+  let controlledRowControlIds = $derived(
+    paginatedTableData.flatMap((row) => {
+      const rowId = rowIdByRow.get(row);
+      const id = renderedCheckboxAttributes.get(row)?.id;
+      return typeof rowId === 'string' && !isRowDisabled(rowId) && id ? [id] : [];
+    })
+  );
+
   // ─── Empty-state reason ───────────────────────────────────────────────────
   // "No records yet" and "nothing matched" need different messages and offer
   // different remedies, and a consumer cannot tell them apart from `rows` alone
@@ -821,7 +849,14 @@
           {#if caption}
             <caption class="sr-only">{caption}</caption>
           {/if}
-          <thead role={mobileRole('rowgroup')}>
+          <thead
+            role={mobileRole('rowgroup')}
+            class:mobile-controls={(isCheckboxMode && !isSingleSelect) ||
+              (hasSearchConfig && isInlineSearch) ||
+              effectiveHeaders.some(
+                (_header, index) => isColumnSortable(index) || Boolean(columns?.[index]?.tooltip)
+              )}
+          >
             <tr role={mobileRole('row')}>
               {#if isCheckboxMode && !isSingleSelect}
                 <th
@@ -837,10 +872,8 @@
                     controlled
                     checked={headerCheckboxState === 'all'}
                     indeterminate={headerCheckboxState === 'some'}
-                    ariaControls={selectableRowIds
-                      .map((rowId) => `row-checkbox-${rowId}`)
-                      .join(' ')}
-                    attributes={checkboxAttributes('__header__', -1)}
+                    ariaControls={controlledRowControlIds.join(' ')}
+                    attributes={headerCheckboxAttributes}
                     onclick={toggleAllSelection}
                   />
                 </th>
@@ -1096,7 +1129,7 @@
                         controlled
                         checked={rowSelected}
                         disabled={rowDisabled}
-                        attributes={checkboxAttributes(rowId, rowIndex)}
+                        attributes={renderedCheckboxAttributes.get(row)}
                         onclick={() => toggleRowSelection(rowId)}
                       />
                     </td>
@@ -1148,9 +1181,16 @@
                             {rowIndex}
                             {originalIndex}
                             {usePortal}
+                            ariaLabel={labels
+                              ?.cellEditor?.(
+                                cellLabel,
+                                rowLabels.get(row) ?? `row ${originalIndex + 1}`
+                              )
+                              ?.trim() ||
+                              `${cellLabel} for ${rowLabels.get(row) ?? `row ${originalIndex + 1}`}`}
                           />
                         {:else if typeof cell === 'function'}
-                          {@render cell(cellValue, rowIndex, colIndex)}
+                          {@render cell(cellValue, rowIndex, colIndex, originalIndex)}
                         {:else}
                           {cellValue}
                         {/if}
@@ -1790,6 +1830,7 @@
     align-items: center;
     gap: var(--table-paginator-gap, 12px);
     flex-wrap: wrap;
+    min-width: 0;
   }
 
   .table-paginator-controls :global(.pagination) {
@@ -1872,6 +1913,10 @@
     .table-mobile-cards td {
       display: block;
       width: 100%;
+      /* `width: 100%` is the card's outer width only if padding and border are
+         inside it: the card row has both, so under content-box it was 26px wider
+         than the table and its right edge ran past the column. */
+      box-sizing: border-box;
     }
 
     /* Headers are not shown as a row anymore -- their text now repeats per
@@ -1891,6 +1936,19 @@
       border-width: 0;
     }
 
+    /* A screen-reader-only header must not conceal operative sort or select-all
+       controls. Keep those headers visible above the record cards, with the same
+       controls, names and table relationships used at desktop width. */
+    .table-mobile-cards thead.mobile-controls {
+      position: static;
+      width: 100%;
+      height: auto;
+      overflow: visible;
+      clip: auto;
+      clip-path: none;
+      white-space: normal;
+    }
+
     /* The horizontal-scroll affordance this table uses at desktop width (see
        .table-scroll / .table-scroll-shell above) has nothing to scroll once
        every cell is a full-width block, and a lingering scrim would fade a

package/dist/Table/a11y.d.ts

@@ -0,0 +1,7 @@
+import type { TableCellValue, TableColumn } from './properties';
+/** Readable row context, independent of editable/selected control values. */
+export declare function rowContextLabel(row: readonly TableCellValue[], originalIndex: number, columns?: readonly TableColumn[]): string;
+/** Constructed once per data projection, then read without mutation by Table. */
+export declare function rowContextLabels(rows: readonly TableCellValue[][], columns?: readonly TableColumn[]): ReadonlyMap<TableCellValue[], string>;
+/** Opaque per-instance IDs: distinct raw keys never collapse through slugging. */
+export declare function selectionControlIds(instanceId: string): (key: string, header: boolean, requestedId?: string) => string;

package/dist/Table/a11y.js

@@ -0,0 +1,71 @@
+const controlTypes = new Set(['input', 'select', 'toggle', 'button', 'action-group', 'popup-menu']);
+/** Readable row context, independent of editable/selected control values. */
+export function rowContextLabel(row, originalIndex, columns) {
+    for (const [index, value] of row.entries()) {
+        if (controlTypes.has(columns?.[index]?.type ?? '')) {
+            continue;
+        }
+        if (typeof value === 'string' && value.trim() !== '') {
+            return value;
+        }
+        if (typeof value === 'number') {
+            return String(value);
+        }
+        if (value && typeof value === 'object' && !Array.isArray(value)) {
+            for (const key of ['text1', 'text', 'label', 'title', 'name']) {
+                const text = value[key];
+                if (typeof text === 'string' && text.trim() !== '') {
+                    return text;
+                }
+            }
+        }
+    }
+    return `row ${originalIndex + 1}`;
+}
+/** Constructed once per data projection, then read without mutation by Table. */
+export function rowContextLabels(rows, columns) {
+    const captions = rows.map((row, index) => rowContextLabel(row, index, columns));
+    const counts = new Map();
+    for (const label of captions) {
+        counts.set(label, (counts.get(label) ?? 0) + 1);
+    }
+    return new Map(rows.map((row, index) => [
+        row,
+        (counts.get(captions[index]) ?? 0) > 1
+            ? `${captions[index]}, record ${index + 1}`
+            : captions[index]
+    ]));
+}
+/** Opaque per-instance IDs: distinct raw keys never collapse through slugging. */
+export function selectionControlIds(instanceId) {
+    const rows = new Map();
+    const owners = new Map();
+    const headerId = `table-${instanceId}-select-all`;
+    owners.set(headerId, 'header');
+    let sequence = 0;
+    const rowId = (key) => {
+        let id = rows.get(key);
+        if (typeof id !== 'string') {
+            do {
+                id = `table-${instanceId}-row-selection-${++sequence}`;
+            } while (owners.has(id));
+            rows.set(key, id);
+            owners.set(id, `row:${key}`);
+        }
+        return id;
+    };
+    return (key, header, requestedId) => {
+        const owner = header ? 'header' : `row:${key}`;
+        const generated = header ? headerId : rowId(key);
+        // Valid caller IDs remain usable for external labels/CSS. Invalid or conflicting
+        // IDs fall back to the managed ID; ownership persists across filter/page changes.
+        if (typeof requestedId === 'string' &&
+            requestedId !== '' &&
+            !/\s/.test(requestedId) &&
+            (!owners.has(requestedId) || owners.get(requestedId) === owner)) {
+            owners.set(requestedId, owner);
+            return requestedId;
+        }
+        return generated;
+    };
+}

package/dist/Table/cellData.js

@@ -154,6 +154,9 @@ export const asSelectCellData = (value) => {
         options.push({ id: optionRecord.id, label: optionRecord.label });
     }
     const selectData = { options };
+    if (typeof record.ariaLabel === 'string') {
+        selectData.ariaLabel = record.ariaLabel;
+    }
     if (typeof record.selectedId === 'string') {
         selectData.selectedId = record.selectedId;
     }

package/dist/Table/properties.d.ts

@@ -128,6 +128,8 @@ export type TableSelectCellData = {
     selectedId?: string;
     placeholder?: string;
     disabled?: boolean;
+    /** Overrides the generated column/row field name on the real combobox. */
+    ariaLabel?: string;
     testId?: string;
     /** Per-option test id prefix — each option emits `data-pw="{itemTestId}-{id}"`. */
     itemTestId?: string;
@@ -349,7 +351,7 @@ export type TableColumn = {
  * - `onSelectionChange` — called whenever the selection set changes, receives
  *   the new set of selected row IDs.
  * - `getRowId` — derives a stable string ID from a row + its index. Defaults
- *   to `String(rowIndex)` when omitted.
+ *   to the original source index when omitted.
  * - `disabledRowIds` — rows whose IDs appear in this set render a disabled,
  *   unchecked checkbox and cannot be selected.
  */
@@ -376,7 +378,9 @@ export type TableCheckboxSelectionConfig = {
     /**
      * Generic DOM-attribute spread onto each row checkbox (`rowIndex` is `-1`
      * for the header select-all). An escape hatch for consumer-specific
-     * attributes (e.g. native test IDs) without the library learning them.
+     * attributes (e.g. native test IDs) without the library learning them. A custom
+     * `id` must be stable and unique within its DOM scope; blank, whitespace-bearing
+     * or conflicting IDs use the generated per-instance control ID instead.
      */
     getRowAttributes?: (rowId: string, rowIndex: number) => Record<string, string>;
 };
@@ -521,8 +525,8 @@ export type TableProperties = OptionalTableProperties & TableEventProperties;
  * not ship an English UI.
  *
  * Every member is optional and falls back to an English default. All but
- * `rowsPerPage` keep the string Table has always used; `rowsPerPage` adds a
- * name to a control that previously had none.
+ * `rowsPerPage` and `cellEditor` keep the string Table has always used; those
+ * two add a name to a control that previously had none.
  *
  * The two that depend on a column, and the one that depends on a row, are
  * functions rather than templates with a placeholder: a translator needs to
@@ -547,6 +551,8 @@ export type TableLabels = {
     clearSearch?: string;
     /** Button that dismisses the search box. Default: `Close search`. */
     closeSearch?: string;
+    /** Built-in editor name. Default: `${columnLabel} for ${rowLabel}`. */
+    cellEditor?: (columnLabel: string, rowLabel: string) => string;
     /** Page-size selector in the built-in paginator footer. Default: `Rows per page`. */
     rowsPerPage?: string;
 };
@@ -667,7 +673,9 @@ export type OptionalTableProperties = {
     sortAscIcon?: Snippet;
     sortDescIcon?: Snippet;
     sortDefaultIcon?: Snippet;
-    cell?: Snippet<[JSONValue, number, number]>;
+    /** Value, current row index, column index and stable original source index.
+     * Existing three-parameter snippets keep working and may ignore the added index. */
+    cell?: Snippet<[JSONValue, number, number, number]>;
     /**
      * Rendered in place of the rows when the view has none. Receives why
      * (`TableEmptyContext`) so one snippet can serve both "no records yet" and

package/dist/ThemeSwitcher/ThemeSwitcher.svelte

@@ -33,6 +33,10 @@
     onchange
   }: ThemeSwitcherProperties = $props();
 
+  // `value` is the INITIAL selection, not a controlled binding (docs/ThemeSwitcher.md): once
+  // mounted the switcher owns the selection -- clicks, the stored preference and onMount below
+  // move it -- so a later change to the prop is deliberately not followed.
+  // svelte-ignore state_referenced_locally
   let currentValue: string = $state(value ?? 'system');
   let systemPreference: string = $state('light');