@juspay/svelte-ui-components 4.7.0 → 4.9.0

package/dist/Card/Card.svelte

@@ -17,10 +17,27 @@
     footer,
     stretch = false,
     scrollable = false,
-    cssVars
+    cssVars,
+    attrs,
+    as
   }: CardProperties = $props();
 
-  const isAnchor = $derived(typeof href === 'string' && href.length > 0);
+  // `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
+  // resolution as before this prop existed.
+  const rootTag = $derived(as ?? (typeof href === 'string' && href.length > 0 ? 'a' : 'div'));
+  // Anchor-only attributes/behaviour (href/target/rel, and skipping the
+  // synthetic role/tabindex/keydown shim) key off the *resolved* tag rather
+  // than `href` alone, so `as="figure"` on an href-carrying Card renders a
+  // real `<figure>` with no dangling `href` attribute instead of a
+  // contradictory figure-that-navigates. It also requires `href` to actually
+  // be set: `as="a"` with an `onclick` but no `href` renders a bare `<a>`
+  // with nothing to navigate to, which is not natively focusable or
+  // keyboard-activatable, so treating it as an anchor here would silently
+  // drop the interactive-div keyboard shim (role/tabindex/onkeydown) with no
+  // native behaviour to replace it.
+  const isAnchor = $derived(rootTag === 'a' && typeof href === 'string' && href.length > 0);
   const isInteractive = $derived(isAnchor || typeof onclick === 'function');
   // HTML target values are ASCII case-insensitive (e.g. "_BLANK" opens a new
   // context identically to "_blank"), so the comparison must normalize case
@@ -50,7 +67,8 @@
 </script>
 
 <svelte:element
-  this={isAnchor ? 'a' : 'div'}
+  this={rootTag}
+  {...attrs ?? {}}
   class="card {classes ?? ''}"
   class:card-interactive={isInteractive}
   class:card-stretch={stretch}

package/dist/Card/properties.d.ts

@@ -82,4 +82,36 @@ export type OptionalCardProperties = {
      * rendered, so existing consumers are unchanged.
      */
     cssVars?: Record<string, string | number>;
+    /**
+     * Arbitrary attributes spread onto the card root — `data-*`/`aria-*` (or any
+     * other) attribute names mapped to string values. For consumers that key
+     * off attribute-selector CSS (`[data-state="waiting"]`, `[data-density]`,
+     * `[data-offline]`) the way the rest of their app does, instead of adding a
+     * second `classes` modifier for the same state. Applied before Card's own
+     * `class`/`style`/`data-pw`/`testID`/`role`/`tabindex`/`href`/`target`/`rel`/
+     * `onclick`/`onkeydown` attributes, so an entry here can never override one
+     * of those — only add attributes Card does not already manage. Omitted by
+     * default, so existing consumers render exactly the same attributes as
+     * before.
+     */
+    attrs?: Record<string, string>;
+    /**
+     * Overrides the tag `svelte:element` renders for the card root — e.g.
+     * `'figure'` for a card that needs real `<figure>` semantics (so a
+     * `<figcaption>` inside `children` or `footer` is valid markup, and the
+     * element carries sectioning-content semantics no wrapper `<figure>` around
+     * a `<div>`-rooted Card could give it).
+     *
+     * When omitted, the root keeps its existing behaviour exactly: `'a'` when
+     * `href` is set, `'div'` otherwise. Setting `as` to anything other than
+     * `'a'` renders that tag instead and suppresses the anchor
+     * attributes/behaviour — `href`/`target`/`rel` are not rendered on it, and
+     * the synthetic `role="button"`/`tabindex`/keydown shim applies instead
+     * when `onclick` is provided, the same as a plain interactive `<div>`.
+     * Setting `as="a"` renders an `<a>` with `href`/`target`/`rel` when `href`
+     * is also set; with `as="a"` but no `href` there is nothing to navigate
+     * to, so the element gets the same interactive-div keyboard shim an
+     * `onclick`-only `<div>` gets instead of anchor semantics it can't have.
+     */
+    as?: 'div' | 'a' | 'figure';
 };

package/dist/ChatComposer/ChatComposer.svelte

@@ -8,11 +8,16 @@
   import attachSvg from '../assets/attach.svg?raw';
   import type { Action } from 'svelte/action';
   import type { ChatComposerProperties } from './properties';
+  import { resolveControlDisabled } from './controlDisabled';
+  import { shouldApplyClear } from './submitResult';
 
   let {
     value = $bindable(''),
     placeholder = '',
     disabled = false,
+    textDisabled = null,
+    voiceDisabled = null,
+    sendDisabled = null,
     submitOnEnter = true,
     maxLength = 0,
     streaming = false,
@@ -75,8 +80,15 @@
     richImages.length > 0 || richVideos.length > 0 || richFiles.length > 0
   );
 
+  // #526: each falls back to the shared `disabled` when its own flag is
+  // unset, so a caller who never passes the new props keeps the original
+  // single-`disabled`-gates-everything behaviour exactly.
+  let resolvedTextDisabled = $derived(resolveControlDisabled(textDisabled, disabled));
+  let resolvedVoiceDisabled = $derived(resolveControlDisabled(voiceDisabled, disabled));
+  let resolvedSendDisabled = $derived(resolveControlDisabled(sendDisabled, disabled));
+
   let canSend = $derived(
-    !disabled &&
+    !resolvedSendDisabled &&
       (sendable ?? (value.trim().length > 0 || attachments.length > 0 || hasRichAttachments))
   );
 
@@ -84,9 +96,28 @@
     if (!canSend) {
       return;
     }
-    onsubmit?.(value, attachments);
-    value = '';
-    attachments = [];
+    const submitted = { value, attachments };
+    const result = onsubmit?.(submitted.value, submitted.attachments);
+    if (result instanceof Promise) {
+      // Nothing here disables the composer while the promise settles — the
+      // user is free to keep typing, so the clear only lands if `value` and
+      // `attachments` still match what was actually sent (see shouldApplyClear).
+      // A rejection is treated the same as a resolved `false`: keep the draft.
+      void result.then(
+        (resolved) => {
+          if (shouldApplyClear(resolved, submitted, { value, attachments })) {
+            value = '';
+            attachments = [];
+          }
+        },
+        () => {}
+      );
+      return;
+    }
+    if (shouldApplyClear(result, submitted, { value, attachments })) {
+      value = '';
+      attachments = [];
+    }
   }
 
   function handleKeydown(event: KeyboardEvent): void {
@@ -208,7 +239,7 @@
       data-pw={inputTestId ?? null}
       bind:value
       {placeholder}
-      {disabled}
+      disabled={resolvedTextDisabled}
       rows="1"
       aria-label={inputAriaLabel ?? (placeholder.length > 0 ? placeholder : 'Message')}
       maxlength={maxLength > 0 ? maxLength : null}
@@ -220,7 +251,12 @@
 
     {#if showVoice}
       <div class="control voice" class:recording>
-        <Button onclick={() => onvoice?.()} {disabled} ariaLabel={voiceLabel} testId={voiceTestId}>
+        <Button
+          onclick={() => onvoice?.()}
+          disabled={resolvedVoiceDisabled}
+          ariaLabel={voiceLabel}
+          testId={voiceTestId}
+        >
           {#if typeof voiceIcon === 'function'}
             {@render voiceIcon()}
           {:else}
@@ -244,7 +280,12 @@
       </div>
     {:else if typeof onaction === 'function' && !canSend && !recording}
       <div class="control send action" data-pw={sendSlotTestId ?? null}>
-        <Button onclick={() => onaction()} {disabled} ariaLabel={actionLabel} testId={actionTestId}>
+        <Button
+          onclick={() => onaction()}
+          disabled={resolvedSendDisabled}
+          ariaLabel={actionLabel}
+          testId={actionTestId}
+        >
           {#if typeof actionIcon === 'function'}
             {@render actionIcon()}
           {:else}

package/dist/ChatComposer/controlDisabled.d.ts

@@ -0,0 +1,10 @@
+/**
+ * #526: `disabled` used to gate the textarea, the voice button and the send
+ * button together — a caller mid-send with dictation running had no way to
+ * freeze the send button without also freezing the mic. `textDisabled`,
+ * `voiceDisabled` and `sendDisabled` let a caller override one control at a
+ * time; leaving a specific flag at its `null` default falls back to the
+ * shared `disabled`, so the single-prop behaviour is exactly what a caller
+ * who never passes the new props keeps getting.
+ */
+export declare function resolveControlDisabled(specific: boolean | null, disabled: boolean): boolean;

package/dist/ChatComposer/controlDisabled.js

@@ -0,0 +1,12 @@
+/**
+ * #526: `disabled` used to gate the textarea, the voice button and the send
+ * button together — a caller mid-send with dictation running had no way to
+ * freeze the send button without also freezing the mic. `textDisabled`,
+ * `voiceDisabled` and `sendDisabled` let a caller override one control at a
+ * time; leaving a specific flag at its `null` default falls back to the
+ * shared `disabled`, so the single-prop behaviour is exactly what a caller
+ * who never passes the new props keeps getting.
+ */
+export function resolveControlDisabled(specific, disabled) {
+    return specific ?? disabled;
+}

package/dist/ChatComposer/properties.d.ts

@@ -5,6 +5,22 @@ export type OptionalChatComposerProperties = {
     value?: string;
     placeholder?: string;
     disabled?: boolean;
+    /**
+     * Disables only the textarea. `null` (the default) falls back to `disabled`,
+     * so a caller that never sets this keeps today's single-`disabled` behaviour
+     * exactly.
+     */
+    textDisabled?: boolean | null;
+    /**
+     * Disables only the voice button. `null` (the default) falls back to
+     * `disabled` — see `textDisabled`.
+     */
+    voiceDisabled?: boolean | null;
+    /**
+     * Disables only the send (and idle-action) button, independent of `sendable`.
+     * `null` (the default) falls back to `disabled` — see `textDisabled`.
+     */
+    sendDisabled?: boolean | null;
     submitOnEnter?: boolean;
     maxLength?: number;
     streaming?: boolean;
@@ -72,7 +88,13 @@ export type OptionalChatComposerProperties = {
     classes?: string;
 };
 export type ChatComposerEventProperties = {
-    onsubmit?: (value: string, attachments: File[]) => void;
+    /**
+     * Fires on submit with the value and pending attachments. May return
+     * `boolean | Promise<boolean>`: an explicit `false` (sync or resolved) skips
+     * the automatic clear so a rejected send can restore its draft — anything
+     * else, including today's `void` return, clears exactly as before.
+     */
+    onsubmit?: (value: string, attachments: File[]) => boolean | void | Promise<boolean | void>;
     oninput?: (value: string, event: Event) => void;
     onkeydown?: (event: KeyboardEvent) => void;
     onpaste?: (event: ClipboardEvent) => void;

package/dist/ChatComposer/submitResult.d.ts

@@ -0,0 +1,34 @@
+/**
+ * #526: `onsubmit` may now return `boolean | Promise<boolean>` instead of only
+ * `void`, so a caller can keep the composer's text (and attachments) around
+ * when a send fails rather than losing the draft to the unconditional clear.
+ *
+ * The rule is deliberately narrow: only an explicit `false` — synchronous or
+ * resolved — skips the clear. Every other synchronous or resolved outcome,
+ * `void` (today's `void`-returning handlers) included, clears exactly as
+ * before, keeping the default byte-for-byte: a handler written against the
+ * pre-#526 `(value, attachments) => void` shape returns nothing and never
+ * opts in to anything, so it keeps clearing on every submit, same as always.
+ * A rejected promise is the one outcome this module never sees — the caller
+ * (`ChatComposer.svelte`) catches it before either function here runs, and
+ * treats it the same as a resolved `false`: the draft is kept, not cleared.
+ */
+export type ChatComposerSubmitResult = boolean | void;
+export declare function shouldClearAfterSubmit(result: ChatComposerSubmitResult): boolean;
+export type ChatComposerDraft = {
+    value: string;
+    attachments: readonly File[];
+};
+/**
+ * Whether the composer should actually apply the clear once an (async)
+ * `onsubmit` settles. Two things have to hold, not just `shouldClearAfterSubmit`:
+ * the value and the attachments the user is looking at right now must still be
+ * the exact ones that were sent. Between `submit()` firing and a `Promise`
+ * resolving, the user is free to keep typing — the composer never disables
+ * itself just because a submit is in flight — so a clear that only checked the
+ * resolved boolean would wipe out whatever they typed in that window. Compared
+ * by reference for attachments: every mutation (`handleFiles`, `removeAttachment`)
+ * reassigns the array, so an unchanged reference means nothing happened while the
+ * promise was pending.
+ */
+export declare function shouldApplyClear(result: ChatComposerSubmitResult, submitted: ChatComposerDraft, current: ChatComposerDraft): boolean;

package/dist/ChatComposer/submitResult.js

@@ -0,0 +1,20 @@
+export function shouldClearAfterSubmit(result) {
+    return result !== false;
+}
+/**
+ * Whether the composer should actually apply the clear once an (async)
+ * `onsubmit` settles. Two things have to hold, not just `shouldClearAfterSubmit`:
+ * the value and the attachments the user is looking at right now must still be
+ * the exact ones that were sent. Between `submit()` firing and a `Promise`
+ * resolving, the user is free to keep typing — the composer never disables
+ * itself just because a submit is in flight — so a clear that only checked the
+ * resolved boolean would wipe out whatever they typed in that window. Compared
+ * by reference for attachments: every mutation (`handleFiles`, `removeAttachment`)
+ * reassigns the array, so an unchanged reference means nothing happened while the
+ * promise was pending.
+ */
+export function shouldApplyClear(result, submitted, current) {
+    return (shouldClearAfterSubmit(result) &&
+        current.value === submitted.value &&
+        current.attachments === submitted.attachments);
+}

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;
-}, "value" | "open" | "selected" | "inputValue" | "highlightedIndex">;
+}, "open" | "value" | "selected" | "inputValue" | "highlightedIndex">;
 type Combobox = ReturnType<typeof Combobox>;
 export default Combobox;

package/dist/MarkdownText/markdown.js

@@ -62,12 +62,20 @@ function escapeHtml(value) {
  * instead of a hole. Casing is normalised so `'HTTPS:'` narrows the same as
  * `'https:'`, matching how `hasSafeProtocol` reads `URL.protocol` (always
  * lower-case).
+ *
+ * A plain-JS or web-component consumer can hand this anything at runtime --
+ * the type is only enforced at compile time for a Svelte caller. Anything
+ * other than an array (and any non-string element inside it) is ignored
+ * rather than crashing `.map`/`.toLowerCase`, degrading to the unrestricted
+ * default instead of throwing an uncaught TypeError.
  */
 function narrow(defaults, allowedProtocols) {
-    if (!allowedProtocols) {
+    if (!Array.isArray(allowedProtocols)) {
         return defaults;
     }
-    const requested = new Set(allowedProtocols.map((protocol) => protocol.toLowerCase()));
+    const requested = new Set(allowedProtocols
+        .filter((protocol) => typeof protocol === 'string')
+        .map((protocol) => protocol.toLowerCase()));
     return new Set([...defaults].filter((protocol) => requested.has(protocol)));
 }
 function resolveProtocolSets(sanitize) {
@@ -81,9 +89,22 @@ function resolveProtocolSets(sanitize) {
  * output can produce renders normally) -- unlike the protocol allow-lists,
  * there is no built-in default set to fall back to once this exists, so its
  * absence is what keeps old behaviour byte-for-byte.
+ *
+ * Names are normalised to lower-case, matching the normalisation
+ * `allowedProtocols` already gets -- every name `tagAllowed` is called with
+ * (`'a'`, `'img'`, `'h1'`, ...) is lower-case, so an unnormalised `['STRONG']`
+ * would otherwise never match and silently drop the tag it meant to keep.
+ *
+ * As with `narrow`, a plain-JS or web-component consumer can hand this
+ * anything at runtime, so anything other than an array (and any non-string
+ * element inside it) is ignored rather than crashing `.map`/`.toLowerCase`,
+ * degrading to "no restriction" instead of throwing an uncaught TypeError.
  */
 function resolveTagAllowList(allowedTags) {
-    return allowedTags ? new Set(allowedTags) : null;
+    if (!Array.isArray(allowedTags)) {
+        return null;
+    }
+    return new Set(allowedTags.filter((tag) => typeof tag === 'string').map((tag) => tag.toLowerCase()));
 }
 function tagAllowed(allowed, tag) {
     return allowed === null || allowed.has(tag);

package/dist/Modal/Modal.svelte

@@ -1,14 +1,20 @@
 <script lang="ts">
   import type { ModalProperties } from './properties';
-  import { onMount, onDestroy } from 'svelte';
+  import { onMount, onDestroy, tick } from 'svelte';
   import ModalAnimation from '../Animations/ModalAnimation.svelte';
   import OverlayAnimation from '../Animations/OverlayAnimation.svelte';
   import { createDebouncer, lockBodyScroll, unlockBodyScroll } from '../utils';
+  import { focusEntryPoint, focusTrapTabTarget } from './focus-trap';
   import Button from '../Button/Button.svelte';
   import Img from '../Img/Img.svelte';
 
   let overlayDiv: HTMLDivElement | null = $state(null);
+  let modalContent: HTMLDivElement | null = $state(null);
   let backPressed = $state(false);
+  // Captured in onMount right before focus moves in, restored in onDestroy.
+  // Not $state: it's read-once bookkeeping for the mount/destroy pair, not
+  // something the template reacts to.
+  let previouslyFocusedElement: HTMLElement | null = null;
 
   let {
     size = 'fit-content',
@@ -33,14 +39,28 @@
     onsecondarybuttonclick,
     onoverlayclick,
     onkeydown,
+    ondismiss,
     classes,
     overlayBackdropFilter,
     overlayFadeIn = false,
     usePortal = false,
     lockScroll = true,
-    autoDismissAfter = null
+    autoDismissAfter = null,
+    ariaLabel,
+    role,
+    overlayAriaLabel
   }: ModalProperties = $props();
 
+  // The overlay only takes role="button" and becomes keyboard-reachable when a
+  // click on it would actually do something. Without either handler, clicking
+  // or activating it is already a no-op (see handleOverlayClick's guard) --
+  // announcing it as a focusable "button" in that case is worse for assistive
+  // tech than leaving it unannounced, same reasoning already applied to the
+  // header images below.
+  const overlayDismissible = $derived(
+    typeof onoverlayclick === 'function' || typeof ondismiss === 'function'
+  );
+
   let dismissTimer: ReturnType<typeof setTimeout> | null = null;
 
   // Fix [major]: plain const so the debouncer closure retains its internal lastCallTime state
@@ -67,9 +87,27 @@
     };
   };
 
+  // Resolves the real focused element regardless of whether modalContent sits
+  // in the light DOM or inside Modal.wc.svelte's open shadow root.
+  // document.activeElement stops at a shadow boundary and returns the shadow
+  // host itself, never the element actually focused inside it -- getRootNode()
+  // returns that shadow root directly when modalContent is shadow-hosted, and
+  // the owner Document otherwise.
+  const getActiveElement = (): Element | null => {
+    if (modalContent === null) {
+      return null;
+    }
+    const root = modalContent.getRootNode();
+    if (root instanceof Document || root instanceof ShadowRoot) {
+      return root.activeElement;
+    }
+    return null;
+  };
+
   const handlePopstate = (): void => {
     backPressed = true;
     onclose?.();
+    ondismiss?.();
   };
 
   const handleRightImageClick = (event: MouseEvent): void => {
@@ -92,6 +130,7 @@
     if (event.target === overlayDiv) {
       debounce(() => {
         onoverlayclick?.();
+        ondismiss?.();
       });
     }
   };
@@ -101,6 +140,49 @@
     const key = event?.key;
     if (key === 'Escape') {
       onoverlayclick?.();
+      ondismiss?.();
+      return;
+    }
+    if (key === 'Tab') {
+      const target = focusTrapTabTarget({
+        container: modalContent,
+        activeElement: getActiveElement(),
+        shiftKey: event.shiftKey
+      });
+      if (target !== null) {
+        event.preventDefault();
+        target.focus();
+      }
+    }
+  };
+
+  // The overlay's own Enter/Space activation, additional to the shared
+  // handleKeyDown (Escape/Tab/onkeydown-prop) that svelte:window already
+  // delivers here via bubbling -- this handler must not also call
+  // handleKeyDown itself, or every keydown on/under the overlay would run it
+  // twice (once from this direct call, once from the window listener seeing
+  // the same event bubble past it), double-firing onkeydown and, on Escape,
+  // the dismiss callbacks. Enter/Space activation is scoped to this handler,
+  // not folded into handleKeyDown itself, because handleKeyDown also runs
+  // from the window listener for a keypress anywhere in the modal (e.g. an
+  // input field) -- it must not treat every Enter/Space in the modal as an
+  // overlay dismissal. This handler is bound to the overlay div, so a keydown
+  // on any focusable descendant (the back button, a footer button, an input
+  // field) bubbles up and reaches it too -- the target check below is what
+  // actually stops that bubbled Enter/Space from being read as an activation
+  // of the overlay itself, mirroring the guard handleOverlayClick already has
+  // for the click case.
+  const handleOverlayKeyDown = (event: KeyboardEvent): void => {
+    if (
+      (event.key === 'Enter' || event.key === ' ') &&
+      overlayDismissible &&
+      event.target === overlayDiv
+    ) {
+      event.preventDefault();
+      debounce(() => {
+        onoverlayclick?.();
+        ondismiss?.();
+      });
     }
   };
 
@@ -131,6 +213,18 @@
       history.pushState(null, '', window.location.href);
       window.addEventListener('popstate', handlePopstate);
     }
+    // Focus starts inside the dialog once it exists, same as Sheet's trap --
+    // otherwise Tab from wherever the trigger was leaves focus behind it,
+    // outside the trap that was just installed.
+    void tick().then(() => {
+      // Capture whatever had focus (the trigger, typically) right before
+      // moving focus in, so onDestroy can put it back. Shadow-aware for the
+      // same reason the Tab trap is: inside Modal.wc.svelte's open shadow
+      // root, document.activeElement would return the shadow host instead.
+      const active = getActiveElement();
+      previouslyFocusedElement = active instanceof HTMLElement ? active : null;
+      focusEntryPoint(modalContent);
+    });
   });
 
   onDestroy(() => {
@@ -148,6 +242,13 @@
         window.removeEventListener('popstate', handlePopstate);
       }
     }
+    // Restore focus to wherever it was before the modal took it. Guarded on
+    // isConnected: the trigger can have been unmounted while the modal was
+    // open (e.g. the page navigated), and .focus() on a detached element is
+    // a silent no-op at best.
+    if (previouslyFocusedElement !== null && previouslyFocusedElement.isConnected) {
+      previouslyFocusedElement.focus();
+    }
   });
 </script>
 
@@ -155,6 +256,7 @@
 
 {#if typeof content === 'function'}
   <OverlayAnimation fadeIn={overlayFadeIn}>
+    <!-- svelte-ignore a11y_no_noninteractive_tabindex -->
     <div
       bind:this={overlayDiv}
       use:portalAction={{ usePortal }}
@@ -163,14 +265,22 @@
         ? `--modal-overlay-backdrop-filter: ${overlayBackdropFilter};`
         : null}
       onclick={handleOverlayClick}
-      onkeydown={handleKeyDown}
-      role="button"
-      tabindex="0"
+      onkeydown={handleOverlayKeyDown}
+      role={overlayDismissible ? 'button' : null}
+      tabindex={overlayDismissible ? 0 : null}
+      aria-label={overlayAriaLabel ?? null}
       data-pw={testId}
       testID={testId}
     >
       <ModalAnimation enable={enableTransition} {align} {transitionType} {entryAnimation}>
-        <div class="modal-content {size}">
+        <div
+          bind:this={modalContent}
+          class="modal-content {size}"
+          role={role ?? null}
+          aria-modal={role != null ? 'true' : null}
+          aria-label={ariaLabel ?? null}
+          tabindex="-1"
+        >
           {#if (typeof header?.leftImage === 'string' && header.leftImage.length > 0) || (typeof header?.text === 'string' && header.text.length > 0) || (typeof header?.rightImage === 'string' && header.rightImage.length > 0)}
             <div class="header">
               {#if typeof header.leftImage === 'string' && header.leftImage.length > 0}
@@ -300,6 +410,11 @@
     border-radius: var(--modal-border-radius, var(--radius, 4px));
     overflow: var(--modal-content-overflow, auto);
     border-top: var(--modal-content-border-top);
+    /* tabindex="-1" makes this the focus-trap's fallback target when the modal
+       has no focusable content of its own (see focus-trap.ts); it is never in
+       the Tab order itself, so it needs no visible focus ring the way a real
+       focusable element would. Matches Sheet's sheet-panel. */
+    outline: none;
     /* Viewport containment for every size class: only .fit-content used to carry
        a max-height, so a size whose height var is overridden to fit-content (or
        anything taller than the screen) grew past the viewport and pushed its

package/dist/Modal/focus-trap.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Focus-trap utility for Modal (#529). Pure DOM-reading functions, no Svelte
+ * runtime dependency, so they can be unit tested without mounting the
+ * component -- mirrors the split Tooltip already uses for its action logic
+ * (see tooltip-action.test.ts).
+ *
+ * Modal.svelte owns the event wiring (which key was pressed, calling
+ * .focus()); this module owns the two decisions that wiring needs answered:
+ * "what are the edges of the tab order in here" and "given where focus is and
+ * which way Tab was pressed, should it wrap, and to where".
+ */
+export type FocusTrapBoundary = {
+    readonly first: HTMLElement | null;
+    readonly last: HTMLElement | null;
+};
+/**
+ * The first and last focusable descendants of `container`, in DOM order.
+ * Both are null when the container is null or holds nothing focusable.
+ */
+export declare function getFocusTrapBoundary(container: ParentNode | null): FocusTrapBoundary;
+/**
+ * Given a Tab/Shift+Tab keydown inside a focus-trapped container, returns the
+ * element focus should move to, or null when the default browser behavior
+ * (move to the next/previous focusable element) should be left alone.
+ *
+ * Wrapping only happens exactly at an edge: focus sits on the last focusable
+ * element and Tab (not Shift+Tab) was pressed, or focus sits on the first and
+ * Shift+Tab was pressed. Anywhere else in the middle of the tab order, the
+ * browser's own handling is correct and this returns null.
+ */
+export declare function focusTrapTabTarget(params: {
+    readonly container: ParentNode | null;
+    readonly activeElement: Element | null;
+    readonly shiftKey: boolean;
+}): HTMLElement | null;
+/**
+ * Moves focus into `container` -- its first focusable descendant, or the
+ * container itself as a fallback for a modal with no focusable content (it
+ * must carry tabindex="-1" for that fallback to actually take focus). A no-op
+ * when the container is null.
+ */
+export declare function focusEntryPoint(container: HTMLElement | null): void;