@juspay/svelte-ui-components 4.19.1 → 4.21.0

package/dist/Card/Card.svelte

@@ -1,5 +1,6 @@
 <script lang="ts">
   import type { CardProperties } from './properties';
+  import { CARD_MANAGED_ATTRS, discardedAttrWarnings } from '../attrs-discard';
 
   let {
     children,
@@ -22,6 +23,27 @@
     as
   }: CardProperties = $props();
 
+  /*
+   * The runtime half of the `attrs` deprecation (#576). The `@deprecated`
+   * markers on the managed keys only reach someone reading TypeScript; a
+   * plain-JS caller, or anyone driving this as a web component, has no types
+   * and would otherwise still get silence.
+   *
+   * Dev builds only: this is an authoring aid, and warning on every production
+   * render would be noise nobody asked for. `import.meta.env` is absent under
+   * bundlers that do not define it, so the guard reads it defensively and stays
+   * quiet there rather than throwing.
+   *
+   * Deliberately at init rather than in an `$effect`, which this repo bans:
+   * once per mounted instance is what a consumer needs to act on, and it costs
+   * nothing on subsequent updates.
+   */
+  if (import.meta.env?.DEV === true) {
+    for (const message of discardedAttrWarnings('Card', CARD_MANAGED_ATTRS, attrs)) {
+      console.warn(message);
+    }
+  }
+
   // `as`, when given, picks the rendered tag outright. Omitted, the root keeps
   // its existing rule: an `<a>` exactly when `href` is set, a `<div>`
   // otherwise -- so a consumer who never passes `as` gets the identical tag

package/dist/ChatMessage/ChatMessage.svelte

@@ -570,6 +570,11 @@
     opacity: var(--chat-message-blockquote-opacity, 0.85);
   }
 
+  /* Fallback for a bare <table> in caller-supplied `html`, which has no scroll
+     container of its own: it keeps the block treatment so a wide table scrolls
+     rather than overflowing the message. A table that came from `markdown` (or
+     from `renderMarkdown`) arrives inside `.markdown-table-wrapper`, and the
+     rules below take it back out of block layout. */
   .body :global(table) {
     display: block;
     max-width: 100%;
@@ -578,6 +583,40 @@
     margin: 0.5em 0;
   }
 
+  /* The wrapper scrolls, not the table. `display: block` on a <table> is what
+     makes `overflow-x` work on the element itself, but it strips the table's
+     semantics for assistive technology -- a screen reader loses row and column
+     navigation. MarkdownText separates the scroll container from the table for
+     exactly that reason; this component rendered the same wrapper markup and
+     styled the table instead, so a chat table was scrollable and no longer a
+     table. Chat is where markdown tables overwhelmingly land. */
+  .body :global(.markdown-table-wrapper) {
+    display: block;
+    max-width: 100%;
+    overflow-x: auto;
+    margin: 0.5em 0;
+  }
+
+  /* The wrapper is a tab stop (the renderer emits tabindex="0" so the scroll is
+     reachable by keyboard). The browser's default ring already applies; this
+     replaces it with the same 2px treatment the rest of the library uses, since
+     the 1px UA default is easy to miss against a message bubble. */
+  .body :global(.markdown-table-wrapper:focus-visible) {
+    outline: 2px solid var(--chat-message-table-focus-outline-color, #3b82f6);
+    outline-offset: 2px;
+  }
+
+  /* Without an intrinsic width the table is exactly its container's width and a
+     wide table compresses instead of scrolling. `max-content` supplies it;
+     `min-width` keeps a narrow table filling the bubble. */
+  .body :global(.markdown-table-wrapper table) {
+    display: table;
+    width: max-content;
+    min-width: 100%;
+    overflow-x: visible;
+    margin: 0;
+  }
+
   .body :global(th),
   .body :global(td) {
     padding: 5px 10px;

package/dist/Combobox/Combobox.svelte.d.ts

@@ -1,6 +1,6 @@
 import type { ComboboxProperties } from './properties';
 declare const Combobox: import("svelte").Component<ComboboxProperties, {
     getInputRef: () => HTMLInputElement | HTMLTextAreaElement | null;
-}, "open" | "value" | "selected" | "inputValue" | "highlightedIndex">;
+}, "value" | "open" | "selected" | "inputValue" | "highlightedIndex">;
 type Combobox = ReturnType<typeof Combobox>;
 export default Combobox;

package/dist/MarkdownText/MarkdownText.svelte

@@ -8,10 +8,13 @@
     testId,
     classes,
     tableLabel,
+    tableWrapperClass,
     sanitize
   }: MarkdownTextProperties = $props();
 
-  let html = $derived(renderMarkdown(markdown, { breaks, tableLabel, sanitize }));
+  let html = $derived(
+    renderMarkdown(markdown, { breaks, tableLabel, tableWrapperClass, sanitize })
+  );
 </script>
 
 <div

package/dist/MarkdownText/markdown.js

@@ -245,14 +245,32 @@ function annotateExternalLinks(html) {
    scrollable region with a tabindex. */
 const TABLE_OPEN = /<table>/g;
 const TABLE_CLOSE = /<\/table>/g;
-function wrapTables(html, label) {
+const DEFAULT_TABLE_WRAPPER_CLASS = 'markdown-table-wrapper';
+function wrapTables(html, label, wrapperClass) {
     /* `role="region"` without an accessible name announces a landmark the user
        cannot identify, which is worse than no landmark, so the role appears only
        when the caller supplies a name. The tabindex does not depend on it:
        keyboard scrolling should work either way. */
+    /* A caller's class is ADDED, never substituted. The wrapper's own styling --
+       `overflow-x: auto`, the `:focus-visible` ring, and the table's max-content
+       width -- is scoped to `.markdown-table-wrapper` in MarkdownText.svelte, and
+       a Svelte scoped selector cannot be templated to a name supplied at runtime.
+       Substituting the class would leave a `tabindex="0"` element that cannot
+       scroll and shows no focus ring, undoing the fix that made a wide table
+       keyboard-scrollable in the first place. Adding costs a consumer nothing:
+       their own selector still matches, and they can still override by
+       specificity. */
+    const custom = typeof wrapperClass === 'string' ? wrapperClass.trim() : '';
+    // The caller's value lands inside a double-quoted HTML attribute, same as
+    // `label` below -- escaping it the same way is what stops a value like
+    // `" onmouseover="alert(1)` from closing the attribute early and injecting a
+    // new one. The built-in name is a literal and needs no escaping.
+    const classAttr = custom.length > 0
+        ? `${DEFAULT_TABLE_WRAPPER_CLASS} ${escapeHtml(custom)}`
+        : DEFAULT_TABLE_WRAPPER_CLASS;
     const open = typeof label === 'string' && label.length > 0
-        ? `<div class="markdown-table-wrapper" tabindex="0" role="region" aria-label="${escapeHtml(label)}">`
-        : '<div class="markdown-table-wrapper" tabindex="0">';
+        ? `<div class="${classAttr}" tabindex="0" role="region" aria-label="${escapeHtml(label)}">`
+        : `<div class="${classAttr}" tabindex="0">`;
     return html.replace(TABLE_OPEN, `${open}<table>`).replace(TABLE_CLOSE, '</table></div>');
 }
 function instanceFor(options) {
@@ -292,5 +310,7 @@ export function renderMarkdown(markdown, options = {}) {
     }
     /* Inline parsing produces no block elements, so there is no table to wrap. */
     const linked = annotateExternalLinks(output);
-    return options.inline === true ? linked : wrapTables(linked, options.tableLabel);
+    return options.inline === true
+        ? linked
+        : wrapTables(linked, options.tableLabel, options.tableWrapperClass);
 }

package/dist/MarkdownText/properties.d.ts

@@ -20,6 +20,15 @@ export type OptionalMarkdownTextProperties = {
      * worse than none.
      */
     tableLabel?: string;
+    /**
+     * Extra class name added to the scrollable region wrapping each table,
+     * alongside the built-in `markdown-table-wrapper` rather than replacing it
+     * (the wrapper's scroll/focus behaviour is scoped to that class and cannot
+     * be retargeted). Lets a consumer whose own stylesheet targets a different
+     * class keep that styling too. Omitting it, or passing an empty or
+     * whitespace-only string, keeps only `markdown-table-wrapper`.
+     */
+    tableWrapperClass?: string;
     /**
      * Narrow which URL protocols survive on rendered links/images. See
      * `MarkdownSanitizeOptions`.
@@ -104,6 +113,8 @@ export type RenderMarkdownOptions = {
     inline?: boolean;
     /** Accessible name for the scroll region wrapping each table. See `MarkdownTextProperties.tableLabel`. */
     tableLabel?: string;
+    /** Class name for the scroll region wrapping each table. See `MarkdownTextProperties.tableWrapperClass`. */
+    tableWrapperClass?: string;
     /** Narrow the protocol allow-list. See `MarkdownSanitizeOptions`. */
     sanitize?: MarkdownSanitizeOptions;
 };

package/dist/Pill/Pill.svelte

@@ -1,5 +1,6 @@
 <script lang="ts">
   import type { PillProperties } from './properties';
+  import { PILL_MANAGED_ATTRS, discardedAttrWarnings } from '../attrs-discard';
   import Button from '../Button/Button.svelte';
   import closeSvg from '../assets/close.svg?raw';
   import { pillToneClass } from './pillTone';
@@ -23,6 +24,27 @@
     attrs
   }: PillProperties = $props();
 
+  /*
+   * The runtime half of the `attrs` deprecation (#576). The `@deprecated`
+   * markers on the managed keys only reach someone reading TypeScript; a
+   * plain-JS caller, or anyone driving this as a web component, has no types
+   * and would otherwise still get silence.
+   *
+   * Dev builds only: this is an authoring aid, and warning on every production
+   * render would be noise nobody asked for. `import.meta.env` is absent under
+   * bundlers that do not define it, so the guard reads it defensively and stays
+   * quiet there rather than throwing.
+   *
+   * Deliberately at init rather than in an `$effect`, which this repo bans:
+   * once per mounted instance is what a consumer needs to act on, and it costs
+   * nothing on subsequent updates.
+   */
+  if (import.meta.env?.DEV === true) {
+    for (const message of discardedAttrWarnings('Pill', PILL_MANAGED_ATTRS, attrs)) {
+      console.warn(message);
+    }
+  }
+
   let interactive = $derived(typeof onclick === 'function');
 
   // A <button> may not contain another button, and a dismissible pill is inherently two

package/dist/Select/Select.svelte.d.ts

@@ -1,4 +1,4 @@
 import type { SelectProperties } from './properties';
-declare const Select: import("svelte").Component<SelectProperties, {}, "open" | "value">;
+declare const Select: import("svelte").Component<SelectProperties, {}, "value" | "open">;
 type Select = ReturnType<typeof Select>;
 export default Select;

package/dist/Table/Table.svelte

@@ -51,7 +51,8 @@
     summaryRowIndex = null,
     headerTooltipIcon,
     headerTooltipPosition,
-    usePortal = false
+    usePortal = false,
+    labels
   }: TableProperties = $props();
 
   // ─── Keyed column model → positional projection ─────────────────────────────
@@ -646,7 +647,7 @@
         class="table-search-clear"
         type="button"
         onclick={clearSearch}
-        aria-label="Clear search"
+        aria-label={labels?.clearSearch ?? 'Clear search'}
       >
         <!-- eslint-disable svelte/no-at-html-tags -->
         {@html closeSvg}
@@ -688,7 +689,7 @@
                        so the tri-state is computed here and never flipped locally. -->
                   <Checkbox
                     text=""
-                    ariaLabel="Select all rows"
+                    ariaLabel={labels?.selectAllRows ?? 'Select all rows'}
                     controlled
                     checked={headerCheckboxState === 'all'}
                     indeterminate={headerCheckboxState === 'some'}
@@ -773,7 +774,7 @@
                             >
                               <Button
                                 {...triggerProps}
-                                ariaLabel="Filter by {header}"
+                                ariaLabel={labels?.filterBy?.(header) ?? `Filter by ${header}`}
                                 testId={headerColumn.testId &&
                                   `${headerColumn.testId}-filter-trigger`}
                               >
@@ -791,7 +792,10 @@
                     {/if}
                     {#if isColumnSortable(colIndex)}
                       <div class="sort-button">
-                        <Button onclick={() => handleSort(colIndex)} ariaLabel="Sort by {header}">
+                        <Button
+                          onclick={() => handleSort(colIndex)}
+                          ariaLabel={labels?.sortBy?.(header) ?? `Sort by ${header}`}
+                        >
                           {#if sortColumn === colIndex && sortDirection === 'asc'}
                             {#if typeof sortAscIcon === 'function'}
                               {@render sortAscIcon()}
@@ -840,7 +844,7 @@
                             <Button
                               variant="ghost"
                               iconOnly={true}
-                              ariaLabel="Close search"
+                              ariaLabel={labels?.closeSearch ?? 'Close search'}
                               onclick={clearSearch}
                             >
                               {#snippet icon()}
@@ -921,7 +925,8 @@
                     >
                       <Checkbox
                         text=""
-                        ariaLabel={`Select row ${rowId || 'non-selectable'}`}
+                        ariaLabel={labels?.selectRow?.(rowId) ??
+                          `Select row ${rowId || 'non-selectable'}`}
                         controlled
                         checked={rowSelected}
                         disabled={rowDisabled}

package/dist/Table/properties.d.ts

@@ -434,7 +434,39 @@ export type TableSearchConfig = {
     displayMode?: 'toolbar' | 'inline';
 };
 export type TableProperties = OptionalTableProperties & TableEventProperties;
+/**
+ * Accessible names Table generates for its own controls, for callers who do
+ * not ship an English UI.
+ *
+ * Every member is optional and falls back to the English string Table has
+ * always used, so adding this prop changes nothing for existing consumers.
+ *
+ * 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
+ * put the header where their grammar wants it, not where an English sentence
+ * happens to leave a slot.
+ *
+ * `Search` is deliberately absent -- `searchConfig.placeholder` already names
+ * the search input and has since search shipped.
+ */
+export type TableLabels = {
+    /** Sort button on a column header. Default: `Sort by ${header}`. */
+    sortBy?: (header: string) => string;
+    /** Filter trigger on a column header. Default: `Filter by ${header}`. */
+    filterBy?: (header: string) => string;
+    /** Per-row selection checkbox. Receives the row id, or `''` when the row
+     *  cannot be selected -- the default spells that case out rather than
+     *  naming an empty row. Default: `Select row ${rowId || 'non-selectable'}`. */
+    selectRow?: (rowId: string) => string;
+    /** Header checkbox that selects every row on the page. Default: `Select all rows`. */
+    selectAllRows?: string;
+    /** Button that empties the search box. Default: `Clear search`. */
+    clearSearch?: string;
+    /** Button that dismisses the search box. Default: `Close search`. */
+    closeSearch?: string;
+};
 export type OptionalTableProperties = {
+    labels?: TableLabels;
     tableTitle?: string | null;
     tableHeaders?: string[];
     tableData?: Array<JSONValue[]>;

package/dist/_chart/narrationHighlighter.d.ts

@@ -0,0 +1,83 @@
+import type { ChartHighlightAPI } from './highlight';
+/**
+ * Drives a chart's highlight from a growing narration transcript.
+ *
+ * `LineChart`, `BarChart` and `PieChart` hand back a `ChartHighlightAPI` from
+ * `onChartReady`, described there as being "for imperative point highlighting
+ * from external orchestrators (e.g. voice narration sync, step-through
+ * animations)". The socket shipped; the plug did not, so the obvious consumer —
+ * an assistant speaking over a chart — hand-rolled it, together with a registry
+ * of charts and a store of pending highlights.
+ *
+ * None of that is needed here. `getCategories()` is already the label list a
+ * registry would have duplicated, and `highlight(null)` is already the clear
+ * path, so this holds one `ChartHighlightAPI` and nothing else. Passing the API
+ * straight in also removes a race the registry version had to work around: a
+ * registry keyed by chart identity has to tolerate `onChartReady` firing before
+ * the chart is registered, which is a window that does not exist when the
+ * caller simply hands over the object it was given.
+ *
+ * ```ts
+ * let highlighter: NarrationHighlighter | null = null;
+ *
+ * <LineChart {data} onChartReady={(chart) => {
+ *   highlighter = createNarrationHighlighter({ chart });
+ * }} />
+ *
+ * // as each transcript chunk arrives
+ * highlighter?.processText(transcriptSoFar);
+ * // when the assistant starts a new answer
+ * highlighter?.reset();
+ * ```
+ */
+export type NarrationHighlighterOptions = {
+    /** The API handed to `onChartReady` by the chart being narrated. */
+    chart: ChartHighlightAPI;
+    /** Milliseconds a highlight stays up before clearing. Defaults to `2000`. */
+    autoClearMs?: number;
+    /** Match category labels case-sensitively. Defaults to `false`. */
+    caseSensitive?: boolean;
+    /**
+     * Replaces the built-in matching rule. Receives the narration and one
+     * category label, already lower-cased unless `caseSensitive` is set.
+     *
+     * The default matches a label only as a whole word. Substring matching is
+     * available through this hook — `(narration, category) =>
+     * narration.includes(category)` — but is a poor default: category labels are
+     * frequently ordinary words like `Other`, `All` or `None`, especially when
+     * they come from a model's tool output rather than a curated list, and a
+     * substring rule fires `Other` on `otherwise` and `others`.
+     *
+     * Whole-word matching narrows that surface; it does not close it. In "on the
+     * other hand", `other` is genuinely a standalone word, so the label still
+     * matches and no lexical rule could decide otherwise without reading the
+     * sentence. A caller who cannot curate labels should require something
+     * stronger here, and should `reset()` between turns so a mis-fire cannot
+     * outlive one answer.
+     */
+    match?: (narration: string, category: string) => boolean;
+};
+export type NarrationHighlighter = {
+    /**
+     * Reads the transcript so far and highlights the first not-yet-seen category
+     * it names. Returns that category's index, or `null` when the narration named
+     * nothing new.
+     *
+     * Safe to call on every chunk: the transcript is expected to grow, and a
+     * category already highlighted this turn is not highlighted again.
+     */
+    processText: (narration: string) => number | null;
+    /**
+     * Starts a new turn: clears the highlight and forgets which categories have
+     * fired, so they can fire again for the next answer.
+     */
+    reset: () => void;
+    /**
+     * Cancels a pending auto-clear. Call from the owner's teardown.
+     *
+     * Deliberately does not call into the chart: teardown ordering is the
+     * caller's, and the chart may already be gone.
+     */
+    destroy: () => void;
+};
+export declare const createNarrationHighlighter: (options: NarrationHighlighterOptions) => NarrationHighlighter;

package/dist/_chart/narrationHighlighter.js

@@ -0,0 +1,113 @@
+const DEFAULT_AUTO_CLEAR_MS = 2000;
+/** Letters, digits and underscore, so a label is matched only as a whole word. */
+const WORD_CHARACTER = /[\p{L}\p{N}_]/u;
+/**
+ * `charAt` rather than indexing: out of range it returns `''`, which is not a
+ * word character, so the string's edges need no special case.
+ */
+const isWordCharacter = (character) => WORD_CHARACTER.test(character);
+/**
+ * True when `needle` appears in `haystack` bounded by non-word characters.
+ *
+ * Written as a scan rather than a `RegExp` for two reasons: a category label is
+ * caller data and would have to be escaped, and `\b` is defined over ASCII word
+ * characters, so it mismatches labels like `Café` or `北区`. Lookbehind would
+ * solve the second but is not available everywhere this library runs.
+ */
+const occursAsWord = (haystack, needle) => {
+    for (let from = 0; from <= haystack.length - needle.length;) {
+        const at = haystack.indexOf(needle, from);
+        if (at === -1) {
+            return false;
+        }
+        const before = at === 0 ? '' : haystack.charAt(at - 1);
+        const after = haystack.charAt(at + needle.length);
+        if (!isWordCharacter(before) && !isWordCharacter(after)) {
+            return true;
+        }
+        from = at + 1;
+    }
+    return false;
+};
+/**
+ * The type says `number`, but a plain-JS or web-component caller can pass
+ * anything. `NaN` reaches `setTimeout` as an immediate fire, clearing the
+ * highlight before it has been seen, so an unusable delay degrades to the
+ * default rather than breaking the affordance it controls.
+ */
+const resolveAutoClearMs = (value) => {
+    if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
+        return DEFAULT_AUTO_CLEAR_MS;
+    }
+    return value;
+};
+/** `getCategories` is the chart's, and a torn-down chart can throw or return junk. */
+const readCategories = (chart) => {
+    try {
+        const categories = chart.getCategories();
+        if (!Array.isArray(categories)) {
+            return [];
+        }
+        return categories.flatMap((category, sourceIndex) => typeof category === 'string' ? [{ label: category, sourceIndex }] : []);
+    }
+    catch {
+        return [];
+    }
+};
+export const createNarrationHighlighter = (options) => {
+    const { chart, caseSensitive = false, match } = options;
+    const autoClearMs = resolveAutoClearMs(options.autoClearMs ?? null);
+    const fired = new Set();
+    let clearTimer = null;
+    const cancelPendingClear = () => {
+        if (clearTimer !== null) {
+            clearTimeout(clearTimer);
+            clearTimer = null;
+        }
+    };
+    const matches = (narration, category) => match ? match(narration, category) : occursAsWord(narration, category);
+    return {
+        processText: (narration) => {
+            if (typeof narration !== 'string' || narration.length === 0) {
+                return null;
+            }
+            const haystack = caseSensitive ? narration : narration.toLowerCase();
+            const categories = readCategories(chart);
+            /*
+             * Longest label wins. `Q1` is a whole-word match inside `Q1 Europe`, so
+             * taking the first hit would highlight the broader slice while the
+             * narration is naming the narrower one. Ties keep the earlier index,
+             * which makes the choice stable across calls.
+             */
+            let bestIndex = null;
+            let bestLength = 0;
+            categories.forEach(({ label, sourceIndex }) => {
+                if (label.length === 0 || fired.has(sourceIndex) || label.length <= bestLength) {
+                    return;
+                }
+                const needle = caseSensitive ? label : label.toLowerCase();
+                if (matches(haystack, needle)) {
+                    bestIndex = sourceIndex;
+                    bestLength = label.length;
+                }
+            });
+            if (bestIndex === null) {
+                return null;
+            }
+            fired.add(bestIndex);
+            cancelPendingClear();
+            chart.highlight(bestIndex);
+            clearTimer = setTimeout(() => {
+                clearTimer = null;
+                chart.highlight(null);
+            }, autoClearMs);
+            return bestIndex;
+        },
+        reset: () => {
+            cancelPendingClear();
+            fired.clear();
+            chart.highlight(null);
+        },
+        destroy: cancelPendingClear
+    };
+};

package/dist/attrs-discard.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Runtime counterpart to the `@deprecated` markers on `attrs` (#576).
+ *
+ * Both Card and Pill spread `attrs` onto their root FIRST and write their own
+ * managed attributes after, so an entry for a managed key is accepted, spread,
+ * and then overwritten. 4.19.0 made that visible in the type by deprecating
+ * those keys, which reaches someone reading TypeScript in an editor and nobody
+ * else: a plain-JS consumer, or anyone driving `<sui-card>` / `<sui-pill>` as a
+ * web component, has no types at all and still gets silence.
+ *
+ * These maps carry the same guidance the `@deprecated` tags carry, as data the
+ * components can read at runtime. `attrs-discard.test.ts` pins each list
+ * against its `*StrictAttrs` type so the two cannot drift apart.
+ */
+/** What Card writes on its own root, and what a consumer should reach for instead. */
+export declare const CARD_MANAGED_ATTRS: {
+    readonly class: "use the `classes` prop";
+    readonly style: "use the `cssVars` prop";
+    readonly role: "Card derives it from `onclick`/`href`; there is no prop for it";
+    readonly tabindex: "Card derives it from `onclick`/`href`; there is no prop for it";
+    readonly href: "use the `href` prop";
+    readonly target: "use the `target` prop";
+    readonly rel: "use the `rel` prop";
+    readonly onclick: "use the `onclick` prop";
+    readonly onkeydown: "Card binds its own to activate on Enter/Space; there is no prop for it";
+    readonly 'data-pw': "use the `testId` prop";
+    readonly testID: "use the `testId` prop";
+};
+/** What Pill writes on its own root, and what a consumer should reach for instead. */
+export declare const PILL_MANAGED_ATTRS: {
+    readonly class: "use the `classes` prop";
+    readonly type: "Pill always supplies `type=\"button\"` on a button root; there is no prop for it";
+    readonly role: "Pill derives it from whether it is interactive; there is no prop for it";
+    readonly tabindex: "Pill derives it from whether it is interactive; there is no prop for it";
+    readonly title: "use the `title` prop";
+    readonly onclick: "use the `onclick` prop";
+    readonly onkeydown: "Pill binds its own to activate on Enter/Space; there is no prop for it";
+    readonly 'data-pw': "use the `testId` prop";
+    readonly testID: "use the `testId` prop";
+    readonly 'aria-disabled': "Pill derives it from the `disabled` prop";
+    readonly 'aria-expanded': "Pill derives it from the `ariaExpanded` prop";
+    readonly 'aria-pressed': "Pill derives it from the `ariaPressed` prop";
+};
+/**
+ * The messages for every managed key present in `attrs`, in the order the
+ * component's own list declares them. Pure: the caller decides whether the
+ * environment is one that should be told, and does the reporting.
+ *
+ * `attrs` is the optional trailing parameter so an absent one is simply not
+ * passed: the repo bans the `undefined` keyword outright.
+ *
+ * Only own properties count. An object built on a prototype that happens to
+ * carry `class` did not ask for that attribute to be spread, and warning about
+ * it would be noise a consumer cannot act on.
+ */
+export declare const discardedAttrWarnings: (component: string, managed: Readonly<Record<string, string>>, attrs?: Readonly<Record<string, string>>) => readonly string[];

package/dist/attrs-discard.js

@@ -0,0 +1,64 @@
+/**
+ * Runtime counterpart to the `@deprecated` markers on `attrs` (#576).
+ *
+ * Both Card and Pill spread `attrs` onto their root FIRST and write their own
+ * managed attributes after, so an entry for a managed key is accepted, spread,
+ * and then overwritten. 4.19.0 made that visible in the type by deprecating
+ * those keys, which reaches someone reading TypeScript in an editor and nobody
+ * else: a plain-JS consumer, or anyone driving `<sui-card>` / `<sui-pill>` as a
+ * web component, has no types at all and still gets silence.
+ *
+ * These maps carry the same guidance the `@deprecated` tags carry, as data the
+ * components can read at runtime. `attrs-discard.test.ts` pins each list
+ * against its `*StrictAttrs` type so the two cannot drift apart.
+ */
+/** What Card writes on its own root, and what a consumer should reach for instead. */
+export const CARD_MANAGED_ATTRS = {
+    class: 'use the `classes` prop',
+    style: 'use the `cssVars` prop',
+    role: 'Card derives it from `onclick`/`href`; there is no prop for it',
+    tabindex: 'Card derives it from `onclick`/`href`; there is no prop for it',
+    href: 'use the `href` prop',
+    target: 'use the `target` prop',
+    rel: 'use the `rel` prop',
+    onclick: 'use the `onclick` prop',
+    onkeydown: 'Card binds its own to activate on Enter/Space; there is no prop for it',
+    'data-pw': 'use the `testId` prop',
+    testID: 'use the `testId` prop'
+};
+/** What Pill writes on its own root, and what a consumer should reach for instead. */
+export const PILL_MANAGED_ATTRS = {
+    class: 'use the `classes` prop',
+    type: 'Pill always supplies `type="button"` on a button root; there is no prop for it',
+    role: 'Pill derives it from whether it is interactive; there is no prop for it',
+    tabindex: 'Pill derives it from whether it is interactive; there is no prop for it',
+    title: 'use the `title` prop',
+    onclick: 'use the `onclick` prop',
+    onkeydown: 'Pill binds its own to activate on Enter/Space; there is no prop for it',
+    'data-pw': 'use the `testId` prop',
+    testID: 'use the `testId` prop',
+    'aria-disabled': 'Pill derives it from the `disabled` prop',
+    'aria-expanded': 'Pill derives it from the `ariaExpanded` prop',
+    'aria-pressed': 'Pill derives it from the `ariaPressed` prop'
+};
+/**
+ * The messages for every managed key present in `attrs`, in the order the
+ * component's own list declares them. Pure: the caller decides whether the
+ * environment is one that should be told, and does the reporting.
+ *
+ * `attrs` is the optional trailing parameter so an absent one is simply not
+ * passed: the repo bans the `undefined` keyword outright.
+ *
+ * Only own properties count. An object built on a prototype that happens to
+ * carry `class` did not ask for that attribute to be spread, and warning about
+ * it would be noise a consumer cannot act on.
+ */
+export const discardedAttrWarnings = (component, managed, attrs) => {
+    if (!attrs) {
+        return [];
+    }
+    return Object.keys(managed)
+        .filter((key) => Object.prototype.hasOwnProperty.call(attrs, key))
+        .map((key) => `[svelte-ui-components] ${component}: the "${key}" entry in \`attrs\` is discarded, ` +
+        `because ${component} writes its own "${key}" after spreading \`attrs\` — ${managed[key]}.`);
+};