@juspay/svelte-ui-components 4.25.0 → 4.27.0

package/dist/Select/Select.svelte

@@ -1,6 +1,6 @@
 <script lang="ts">
   import { onMount, tick } from 'svelte';
-  import type { SelectItem, SelectProperties } from './properties';
+  import type { SelectItem, SelectPlacement, SelectProperties } from './properties';
   import Pill from '../Pill/Pill.svelte';
   import Img from '../Img/Img.svelte';
   import { computeSelectDropdownPosition } from './dropdownPosition';
@@ -33,6 +33,7 @@
     classes,
     open = $bindable(false),
     dropdownAlign = 'left',
+    placement,
     hierarchy = 'default',
     leftIcon,
     leftIconTestId,
@@ -62,6 +63,67 @@
   // default. The in-flow panel still honours the CSS var via its margin-top.
   const PORTAL_DROPDOWN_GAP = 4;
 
+  /** Viewport padding the `'auto'` placement keeps between the panel and the edges. */
+  const AUTO_PLACEMENT_VIEWPORT_MARGIN = 8;
+
+  /* An unset `placement` is the pre-5.0 contract, kept exactly: the in-flow panel
+     always opens downward and only the portaled one flips on fit. Setting it opts
+     both paths into one resolved corner, which is the whole point of the prop. */
+  let placementRequest: SelectPlacement = $derived(
+    placement ?? (dropdownAlign === 'right' ? 'bottom-right' : 'bottom-left')
+  );
+  let placementPinned: boolean = $derived(placement != null);
+
+  /** Corner an `'auto'` measuring pass settled on; null until it has run. */
+  let autoResolved: Exclude<SelectPlacement, 'auto'> | null = $state(null);
+
+  /* Derived rather than assigned when the dropdown opens: `open` is bindable and
+     documented as something a parent can drive, so the panel can be rendered
+     without `openDropdown` ever running. Assigning on the click path left an
+     explicitly placed Select rendering at the default corner whenever its parent
+     opened it. */
+  let resolvedPlacement: Exclude<SelectPlacement, 'auto'> = $derived(
+    placementRequest === 'auto' ? (autoResolved ?? 'bottom-left') : placementRequest
+  );
+  /** True while an `'auto'` open measures the hidden panel -- suppresses paint. */
+  let measuringPlacement: boolean = $derived(placementRequest === 'auto' && autoResolved === null);
+
+  /* `$derived.by` rather than `$derived`: a bare expression here is evaluated in
+     the declaration's control flow, where TypeScript has `resolvedPlacement`
+     still narrowed to its initialiser literal and calls the comparison
+     unreachable. The closure resets that narrowing. */
+  let placementAlign: 'left' | 'right' = $derived.by(() =>
+    resolvedPlacement === 'bottom-right' || resolvedPlacement === 'top-right' ? 'right' : 'left'
+  );
+
+  /**
+   * Resolves `'auto'` against live geometry, mirroring Menu's pass: the panel is
+   * rendered hidden at the default corner first so it has real dimensions, then
+   * flips right/up only where the default overflows and the opposite side fits.
+   */
+  function resolveAutoPlacement(panel: HTMLElement): Exclude<SelectPlacement, 'auto'> {
+    if (containerEl === null || typeof window === 'undefined') {
+      return 'bottom-left';
+    }
+    const containerRect = containerEl.getBoundingClientRect();
+    const panelRect = panel.getBoundingClientRect();
+    const viewportWidth = window.innerWidth;
+    const viewportHeight = window.innerHeight;
+
+    const overflowsRight =
+      containerRect.left + panelRect.width > viewportWidth - AUTO_PLACEMENT_VIEWPORT_MARGIN;
+    const fitsRightAnchored =
+      containerRect.right - panelRect.width >= AUTO_PLACEMENT_VIEWPORT_MARGIN;
+    const horizontal = overflowsRight && fitsRightAnchored ? 'right' : 'left';
+
+    const overflowsBottom =
+      containerRect.bottom + panelRect.height > viewportHeight - AUTO_PLACEMENT_VIEWPORT_MARGIN;
+    const fitsAbove = containerRect.top - panelRect.height >= AUTO_PLACEMENT_VIEWPORT_MARGIN;
+    const vertical = overflowsBottom && fitsAbove ? 'top' : 'bottom';
+
+    return `${vertical}-${horizontal}`;
+  }
+
   const instanceId = $props.id();
   const listboxId = `select-listbox-${instanceId}`;
   const errorMessageId = `${listboxId}-error`;
@@ -195,9 +257,9 @@
     return { destroy: () => node.remove() };
   };
 
-  let portalStyle = $derived.by(() => {
+  let portalPlacement = $derived.by(() => {
     if (!usePortal || !open || triggerEl === null) {
-      return '';
+      return null;
     }
     void portalTick;
     const rect = triggerEl.getBoundingClientRect();
@@ -215,13 +277,62 @@
       },
       dropdown: { width: dropdownWidth, height: dropdownHeight },
       viewport,
-      align: dropdownAlign,
+      align: placementAlign,
+      /* Unset `placement` keeps the fit-based flip this path always had; a pinned
+         corner is honoured on both axes instead. */
+      vertical: placementPinned
+        ? resolvedPlacement === 'top-left' || resolvedPlacement === 'top-right'
+          ? 'top'
+          : 'bottom'
+        : 'auto',
       gap: PORTAL_DROPDOWN_GAP
     });
+    return placement;
+  });
+
+  let portalStyle: string = $derived.by(() => {
+    const placement = portalPlacement;
+    if (placement === null) {
+      return '';
+    }
     const widthRule = placement.width === null ? '' : `width:${placement.width}px;`;
     return `top:${placement.top}px;left:${placement.left}px;min-width:${placement.minWidth}px;${widthRule}`;
   });
 
+  /* A portaled panel's side comes from the geometry, which still flips on fit
+     when `placement` is unset. Reporting the requested corner there would make
+     `data-placement` disagree with where the panel actually is -- the exact
+     thing the attribute exists to tell a consumer. */
+  let effectivePlacement: Exclude<SelectPlacement, 'auto'> = $derived.by(() => {
+    const placement = portalPlacement;
+    if (placement === null) {
+      return resolvedPlacement;
+    }
+    if (placement.flippedUp) {
+      return placementAlign === 'right' ? 'top-right' : 'top-left';
+    }
+    return placementAlign === 'right' ? 'bottom-right' : 'bottom-left';
+  });
+
+  /**
+   * Svelte action on the panel itself: `openDropdown` is not the only way the
+   * panel appears, so the `'auto'` measuring pass is driven by the panel's own
+   * lifecycle rather than by the open handler. Resetting on destroy is what
+   * makes a reopen re-measure against the trigger's current position.
+   */
+  const resolveAutoPlacementOnMount = (node: HTMLElement) => {
+    if (placementRequest === 'auto') {
+      void tick().then(() => {
+        autoResolved = resolveAutoPlacement(node);
+      });
+    }
+    return {
+      destroy: () => {
+        autoResolved = null;
+      }
+    };
+  };
+
   async function openDropdown(): Promise<void> {
     if (disabled || open) {
       return;
@@ -792,8 +903,13 @@
            the inner element that actually holds the options. -->
       <div
         class="select-dropdown"
-        class:select-dropdown-right={dropdownAlign === 'right'}
+        class:select-dropdown-right={placementAlign === 'right'}
+        class:select-dropdown-up={!usePortal &&
+          (effectivePlacement === 'top-left' || effectivePlacement === 'top-right')}
+        class:select-dropdown-measuring={measuringPlacement}
         class:select-dropdown-portal={usePortal}
+        data-placement={effectivePlacement}
+        use:resolveAutoPlacementOnMount
         bind:this={dropdownEl}
         bind:clientWidth={dropdownWidth}
         bind:clientHeight={dropdownHeight}
@@ -841,8 +957,13 @@
     {:else}
       <div
         class="select-dropdown"
-        class:select-dropdown-right={dropdownAlign === 'right'}
+        class:select-dropdown-right={placementAlign === 'right'}
+        class:select-dropdown-up={!usePortal &&
+          (effectivePlacement === 'top-left' || effectivePlacement === 'top-right')}
+        class:select-dropdown-measuring={measuringPlacement}
         class:select-dropdown-portal={usePortal}
+        data-placement={effectivePlacement}
+        use:resolveAutoPlacementOnMount
         bind:this={dropdownEl}
         bind:clientWidth={dropdownWidth}
         bind:clientHeight={dropdownHeight}
@@ -1045,6 +1166,23 @@
     height: 100%;
   }
 
+  /* Anchors the in-flow panel above the trigger. `margin-top` is what the
+     downward panel uses for the gap, so it has to be unset here or the panel
+     sits a gap's width too high. */
+  .select-dropdown.select-dropdown-up {
+    top: auto;
+    bottom: 100%;
+    margin-top: 0;
+    margin-bottom: var(--select-dropdown-gap, 4px);
+  }
+
+  /* One-tick measuring pass for placement="auto": the panel needs rendered
+     dimensions before the corner is chosen, without a visible flash at the
+     wrong corner. */
+  .select-dropdown.select-dropdown-measuring {
+    visibility: hidden;
+  }
+
   .select-dropdown {
     position: absolute;
     top: 100%;

package/dist/Select/dropdownPosition.d.ts

@@ -9,6 +9,12 @@ type Size = {
     width: number;
     height: number;
 };
+/**
+ * Which side of the trigger the panel opens on. `'auto'` picks the side that
+ * fits, which is what a portaled Select did before `placement` existed and so
+ * stays the default when the option is omitted.
+ */
+export type SelectVerticalPlacement = 'bottom' | 'top' | 'auto';
 export type SelectDropdownPlacement = {
     left: number;
     top: number;
@@ -28,14 +34,16 @@ export type SelectDropdownPlacement = {
  * coordinates for a `position: fixed` panel anchored to `trigger`. Left-aligned
  * panels match the trigger width; right-aligned panels hang leftward from the
  * trigger's right edge using their measured content width. The panel flips above
- * the trigger only when it cannot fit below and there is more room above, and is
- * clamped horizontally to a viewport margin.
+ * the trigger only when it cannot fit below and there is more room above — or
+ * unconditionally when `vertical` pins a side — and is clamped horizontally to a
+ * viewport margin.
  */
 export declare function computeSelectDropdownPosition(opts: {
     trigger: TriggerRect;
     dropdown: Size;
     viewport: Size;
     align: 'left' | 'right';
+    vertical?: SelectVerticalPlacement;
     gap: number;
     margin?: number;
 }): SelectDropdownPlacement;

package/dist/Select/dropdownPosition.js

@@ -3,11 +3,13 @@
  * coordinates for a `position: fixed` panel anchored to `trigger`. Left-aligned
  * panels match the trigger width; right-aligned panels hang leftward from the
  * trigger's right edge using their measured content width. The panel flips above
- * the trigger only when it cannot fit below and there is more room above, and is
- * clamped horizontally to a viewport margin.
+ * the trigger only when it cannot fit below and there is more room above — or
+ * unconditionally when `vertical` pins a side — and is clamped horizontally to a
+ * viewport margin.
  */
 export function computeSelectDropdownPosition(opts) {
     const margin = opts.margin ?? 8;
+    const vertical = opts.vertical ?? 'auto';
     const { trigger, dropdown, viewport, align, gap } = opts;
     const minWidth = trigger.width;
     const width = align === 'left' ? trigger.width : null;
@@ -19,7 +21,30 @@ export function computeSelectDropdownPosition(opts) {
     }
     const spaceBelow = viewport.height - trigger.bottom;
     const spaceAbove = trigger.top;
-    const flippedUp = dropdown.height > 0 && spaceBelow < dropdown.height + gap && spaceAbove > spaceBelow;
-    const top = flippedUp ? trigger.top - gap - dropdown.height : trigger.bottom + gap;
+    /* A pinned side is honoured even where the panel will not fit: the caller
+       asked for that side, and silently overriding it is the behaviour
+       `placement` exists to escape. Only `'auto'` consults the geometry. */
+    const fitsBelow = !(dropdown.height > 0 && spaceBelow < dropdown.height + gap);
+    const flippedUp = vertical === 'auto' ? !fitsBelow && spaceAbove > spaceBelow : vertical === 'top';
+    const unclamped = flippedUp ? trigger.top - gap - dropdown.height : trigger.bottom + gap;
+    /* The panel is `position: fixed` when portaled, so whatever a viewport edge
+       cuts off cannot be scrolled back into view -- hence clamping at all. The two
+       edges are not symmetric, though:
+  
+       The top edge is always held. A negative top is unreachable however the side
+       was chosen.
+  
+       The bottom edge is held only for an auto-resolved side. `'auto'` picks the
+       side with more room and can still overflow in a short viewport, where
+       pulling the panel up is right. A *pinned* side is the caller overriding the
+       fit, and dragging it back would park the panel over the very trigger it was
+       pinned below -- the silent override `placement` exists to escape. */
+    const bottomLimit = viewport.height - dropdown.height - margin;
+    const withinViewport = vertical === 'auto' && Number.isFinite(viewport.height)
+        ? Math.min(unclamped, bottomLimit)
+        : unclamped;
+    const top = Number.isFinite(viewport.height) && dropdown.height > 0
+        ? Math.max(margin, withinViewport)
+        : unclamped;
     return { left, top, minWidth, width, flippedUp };
 }

package/dist/Select/properties.d.ts

@@ -1,4 +1,9 @@
 import type { Snippet } from 'svelte';
+/**
+ * Corner the dropdown anchors to. Mirrors `MenuPlacement` so the two components
+ * that open a panel from a trigger describe placement the same way.
+ */
+export type SelectPlacement = 'bottom-left' | 'bottom-right' | 'top-left' | 'top-right' | 'auto';
 export type SelectProperties = MandatorySelectProperties & OptionalSelectProperties & SelectEventProperties;
 export type SelectItem = {
     id: string;
@@ -103,8 +108,23 @@ export type OptionalSelectProperties = {
     classes?: string;
     /** Bindable. Controls whether the dropdown is open; the component writes back on open/close so parents can `bind:open` to observe or drive it. Unbound, the component manages its own state. */
     open?: boolean;
-    /** Horizontal anchor of the dropdown panel. `'left'` (default) anchors to the trigger's left edge; `'right'` anchors to the right edge so a content-wider panel hangs leftward instead of overflowing. */
+    /**
+     * @deprecated Use `placement`, which controls both axes. `dropdownAlign: 'left'`
+     * is `placement: 'bottom-left'` and `'right'` is `'bottom-right'`. Still honoured
+     * when `placement` is not set; scheduled for removal in 5.0.0.
+     */
     dropdownAlign?: 'left' | 'right';
+    /**
+     * Corner the dropdown panel anchors to, matching `Menu`'s prop of the same name.
+     * `'auto'` resolves the best-fitting corner against the viewport on open, so a
+     * Select sitting just above a sticky footer opens upward instead of into it.
+     *
+     * Unset is the pre-5.0 contract and is what `dropdownAlign` still drives: the
+     * in-flow panel always opens downward, and a portaled one flips up only when it
+     * cannot fit below. Setting `placement` opts both paths into the same resolved
+     * corner, so an in-flow Select can finally open upward.
+     */
+    placement?: SelectPlacement;
     /** Snippet for rendering a compact trigger summary in multiple mode instead of one Pill per selected value. Receives `{ value, items }` so the consumer can compute e.g. "All" / "3 selected". When not provided the default Pill-per-value behaviour is used. */
     triggerSummary?: import('svelte').Snippet<[{
         value: string[];