@juspay/svelte-ui-components 4.8.0 → 4.9.0

package/dist/Modal/focus-trap.js

@@ -0,0 +1,57 @@
+/**
+ * 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".
+ */
+const FOCUSABLE_SELECTOR = 'a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
+/**
+ * The first and last focusable descendants of `container`, in DOM order.
+ * Both are null when the container is null or holds nothing focusable.
+ */
+export function getFocusTrapBoundary(container) {
+    if (container === null) {
+        return { first: null, last: null };
+    }
+    const focusable = container.querySelectorAll(FOCUSABLE_SELECTOR);
+    return { first: focusable.item(0), last: focusable.item(focusable.length - 1) };
+}
+/**
+ * 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 function focusTrapTabTarget(params) {
+    const { first, last } = getFocusTrapBoundary(params.container);
+    if (first === null || last === null) {
+        return null;
+    }
+    const edge = params.shiftKey ? first : last;
+    if (params.activeElement !== edge) {
+        return null;
+    }
+    return params.shiftKey ? last : first;
+}
+/**
+ * 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 function focusEntryPoint(container) {
+    if (container === null) {
+        return;
+    }
+    const { first } = getFocusTrapBoundary(container);
+    (first ?? container).focus();
+}

package/dist/Modal/properties.d.ts

@@ -11,6 +11,12 @@ export type ModalAlign = 'top' | 'center' | 'bottom';
  * Leave unset to keep the existing per-align default.
  */
 export type ModalEntryAnimation = 'fade' | 'slide-up' | 'slide-down';
+/**
+ * 'alertdialog' is for a dialog that interrupts to demand an immediate
+ * response (e.g. a destructive confirmation) -- semantically distinct from an
+ * ordinary 'dialog' in how assistive tech announces it. See the `role` prop.
+ */
+export type ModalRole = 'dialog' | 'alertdialog';
 export type ModalProperties = OptionalModalProperties & ModalEventProperties;
 export type OptionalModalProperties = {
     size?: ModalSize;
@@ -38,6 +44,15 @@ export type OptionalModalProperties = {
     leftImageTestId?: string;
     /** Accessible name for the left header image's role="button" wrapper (e.g. a back control). Rendered as aria-label. */
     leftImageAriaLabel?: string;
+    /**
+     * Accessible name for the overlay's `role="button"` wrapper, rendered as
+     * `aria-label` -- same pattern as `leftImageAriaLabel` and
+     * `header.buttonAriaLabel`. Only meaningful when the overlay is dismissible
+     * (an `onoverlayclick` or `ondismiss` handler is supplied), which is the
+     * only state where the overlay is announced as a focusable "button" at all.
+     * Default: unset (no accessible name).
+     */
+    overlayAriaLabel?: string;
     testId?: string;
     content?: Snippet;
     footerSnippet?: Snippet;
@@ -52,6 +67,24 @@ export type OptionalModalProperties = {
     lockScroll?: boolean;
     /** Milliseconds after mount to automatically fire onclose, e.g. for a transient success/confirmation modal. null (default) disables auto-dismiss. */
     autoDismissAfter?: number | null;
+    /**
+     * Accessible name for the modal, rendered as `aria-label` on the modal
+     * content panel (the element carrying `role`/`aria-modal` when `role` is
+     * set). Without it a screen reader announces an unnamed dialog. Default:
+     * unset (no aria-label) -- matches today's behavior, where the panel has no
+     * accessible name at all.
+     */
+    ariaLabel?: string;
+    /**
+     * ARIA role for the modal content panel. Default: unset -- the panel
+     * renders no `role` and no `aria-modal` at all, byte-for-byte matching
+     * behavior prior to this prop's introduction, so an existing consumer who
+     * never touches `role` sees no DOM/ARIA change. Set it explicitly (e.g.
+     * `'dialog'` or `'alertdialog'`) to opt in: the panel then also carries
+     * `aria-modal="true"`, since a role without aria-modal is not a complete
+     * dialog announcement.
+     */
+    role?: ModalRole;
 };
 export type ModalEventProperties = {
     onclose?: () => void;
@@ -61,4 +94,15 @@ export type ModalEventProperties = {
     onsecondarybuttonclick?: (event: MouseEvent) => void;
     onoverlayclick?: () => void;
     onkeydown?: (event: KeyboardEvent) => void;
+    /**
+     * Fires on every path that dismisses the modal from the OUTSIDE: an overlay
+     * click, the Escape key, and a hardware back-press. A superset of
+     * onoverlayclick (backdrop click + Escape only) and onclose (hardware
+     * back-press + autoDismissAfter only) -- wire this single callback instead
+     * of both when all a consumer needs is "the modal wants to close". Both
+     * existing events keep firing unchanged alongside it; autoDismissAfter's
+     * timer still fires only onclose, not ondismiss, since that path is the
+     * modal closing itself rather than something dismissing it.
+     */
+    ondismiss?: () => void;
 };

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

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

package/dist/Sheet/Sheet.svelte

@@ -12,6 +12,7 @@
     showOverlay = true,
     dismissOnOutsideClick = showOverlay,
     showCloseButton = true,
+    headingLevel,
     testId,
     content,
     footer,
@@ -34,6 +35,10 @@
         return { x: 0, y: -400, duration: 300 };
       case 'bottom':
         return { x: 0, y: 400, duration: 300 };
+      // No edge to fly in from — a centered dialog only fades, so x/y stay
+      // at 0 and `fly` degrades to exactly the overlay's own fade transition.
+      case 'center':
+        return { x: 0, y: 0, duration: 300 };
     }
   });
 
@@ -101,6 +106,20 @@
       onafterclose();
     }
   }
+
+  // headingLevel's `1 | 2 | 3 | 4 | 5 | 6` union only constrains Svelte-import
+  // consumers. Through the web component, attributes are untyped strings
+  // coerced to Number — heading-level="7"/"0"/"-1"/"foo" would otherwise reach
+  // `h${headingLevel}` unchecked and render an invalid tag (<h7>, <h0>, <h-1>,
+  // <hNaN>). Validate at runtime and fall back to the existing <span>.
+  const headingTag = $derived(
+    typeof headingLevel === 'number' &&
+      Number.isInteger(headingLevel) &&
+      headingLevel >= 1 &&
+      headingLevel <= 6
+      ? `h${headingLevel}`
+      : null
+  );
 </script>
 
 {#if open}
@@ -135,7 +154,11 @@
       {#if typeof title === 'string' || showCloseButton}
         <div class="sheet-header">
           {#if typeof title === 'string'}
-            <span class="sheet-title">{title}</span>
+            {#if headingTag !== null}
+              <svelte:element this={headingTag} class="sheet-title">{title}</svelte:element>
+            {:else}
+              <span class="sheet-title">{title}</span>
+            {/if}
           {/if}
           {#if showCloseButton}
             <div class="sheet-close-button">
@@ -241,6 +264,20 @@
     border-top: var(--sheet-border, none);
   }
 
+  /* `side="center"` is a fixed-size floating dialog, not an edge-anchored
+     panel: no top/bottom/left/right offset, sized by its own tokens rather
+     than --sheet-width/--sheet-height (so an existing left/right/top/bottom
+     theme is untouched by adding this variant), and centered with a
+     transform instead of stretching to an edge. */
+  .sheet-panel.center {
+    top: 50%;
+    left: 50%;
+    transform: translate(-50%, -50%);
+    width: var(--sheet-center-width, 480px);
+    max-width: var(--sheet-center-max-width, calc(100vw - 32px));
+    max-height: var(--sheet-center-max-height, 90vh);
+  }
+
   .sheet-header {
     display: flex;
     align-items: center;

package/dist/Sheet/properties.d.ts

@@ -1,5 +1,5 @@
 import type { Snippet } from 'svelte';
-export type SheetSide = 'left' | 'right' | 'top' | 'bottom';
+export type SheetSide = 'left' | 'right' | 'top' | 'bottom' | 'center';
 export type SheetProperties = MandatorySheetProperties & OptionalSheetProperties & SheetEventProperties;
 export type MandatorySheetProperties = {
     content: Snippet;
@@ -18,6 +18,14 @@ export type OptionalSheetProperties = {
      */
     dismissOnOutsideClick?: boolean;
     showCloseButton?: boolean;
+    /**
+     * Renders `title` through a real `<h1>`-`<h6>` heading element instead of
+     * the default `<span>`. Omit to keep the existing `<span>` markup
+     * unchanged — the default when this prop is not set. Set it to the level
+     * that is correct in the surrounding document outline (a sheet opened from
+     * a page whose top-level heading is an `<h1>` typically wants `2`).
+     */
+    headingLevel?: 1 | 2 | 3 | 4 | 5 | 6;
     testId?: string;
     footer?: Snippet;
     classes?: string;

package/dist/Toolbar/Toolbar.svelte

@@ -6,6 +6,7 @@
     text,
     backIcon,
     backLabel = 'Back',
+    backHref,
     leftContent,
     centerContent,
     rightContent,
@@ -23,6 +24,22 @@
   // The icon is decorative, so the label is the button's only accessible name — an empty or
   // whitespace-only value must not strip it.
   const backAccessibleName = $derived(backLabel.trim().length > 0 ? backLabel : 'Back');
+  // A real link only when a non-empty href is actually given — same emptiness check the
+  // rest of the component already applies to backIcon, so `backHref=""` behaves like "unset"
+  // rather than rendering a same-page anchor.
+  const hasBackHref = $derived(typeof backHref === 'string' && backHref.length > 0);
+
+  // A native <a> does not fire `click` on Space — only Enter — so the keyboard activation the
+  // old <button> gave for free would silently regress when backHref swaps the tag. Enter already
+  // reaches `onbackclick` through the anchor's native click, so only Space needs help here; the
+  // consumer's own `onkeydown` still runs unconditionally, same as it always has.
+  const handleBackKeydown = (event: KeyboardEvent): void => {
+    onkeydown?.(event);
+    if (hasBackHref && event.key === ' ') {
+      event.preventDefault();
+      onbackclick?.();
+    }
+  };
 </script>
 
 <div class="toolbar {classes ?? ''}" data-pw={testId} testID={testId}>
@@ -34,12 +51,15 @@
     {#if typeof leftContent === 'function'}
       {@render leftContent()}
     {:else if showBackControl}
-      <button
-        type="button"
+      <svelte:element
+        this={hasBackHref ? 'a' : 'button'}
+        type={hasBackHref ? null : 'button'}
+        href={hasBackHref ? backHref : null}
+        role={null}
         class="back"
         aria-label={backAccessibleName}
         onclick={onbackclick}
-        {onkeydown}
+        onkeydown={handleBackKeydown}
       >
         {#if typeof backIcon === 'string'}
           <img src={backIcon} alt="" />
@@ -56,7 +76,7 @@
             />
           </svg>
         {/if}
-      </button>
+      </svelte:element>
     {/if}
     {#if typeof centerContent === 'function'}
       <div class="center-content">

package/dist/Toolbar/properties.d.ts

@@ -4,6 +4,17 @@ export type ToolbarProperties = ToolbarEventProperties & {
     text?: string | null;
     backIcon?: string | null;
     backLabel?: string;
+    /**
+     * Renders the built-in back control as a real `<a href={backHref}>` instead of a
+     * `<button>` — for back navigation that is a real link (browser back-forward, open-in-new-tab,
+     * a working href with JS disabled) rather than only reachable through `onbackclick`.
+     * Omit it (the default) for the existing callback-only `<button>`. `onbackclick`
+     * still fires as the anchor's `click` handler when both are supplied, so navigation and any
+     * side effect (e.g. analytics) coexist exactly as they do on the library's own `Button`
+     * `href` + `onclick`. Ignored when `leftContent` is provided or the back control is hidden
+     * (`showBackButton={false}` or `backIcon={null}`).
+     */
+    backHref?: string;
     leftContent?: Snippet;
     centerContent?: Snippet;
     rightContent?: Snippet;