@svgrid/grid 2.1.21 → 2.1.23

package/dist/SvMenuList.svelte

@@ -1,17 +1,8 @@
 <script lang="ts" module>
-  import type { Snippet } from 'svelte'
-  export type MenuItem = {
-    /** Item text. Omit + set `separator` for a divider. */
-    label?: string
-    separator?: boolean
-    icon?: Snippet
-    /** Right-aligned hint, e.g. a keyboard shortcut. */
-    shortcut?: string
-    disabled?: boolean
-    /** Nested submenu items (renders a flyout). */
-    children?: MenuItem[]
-    onSelect?: () => void
-  }
+  // MenuItem lives in a plain `.ts` module (breaks a Vite dev import cycle); it is
+  // re-exported here so existing `import { type MenuItem } from './SvMenuList.svelte'`
+  // sites keep working.
+  export type { MenuItem } from './menu-item'
 </script>
 
 <script lang="ts">
@@ -22,6 +13,8 @@
    */
   import Self from './SvMenuList.svelte'
   import { type EditorDir } from './editor-contract'
+  import type { MenuItem } from './menu-item'
+  import { createMenu } from './createMenu.svelte'
 
   let {
     items,
@@ -46,56 +39,24 @@
     dir?: EditorDir
   } = $props()
 
-  // Indexes of real (non-separator) items, for roving focus.
-  const focusable = $derived(items.map((it, i) => (it.separator || it.disabled ? -1 : i)).filter((i) => i >= 0))
-  let active = $state(-1)
-  let openSub = $state(-1)
   let listEl = $state<HTMLDivElement | null>(null)
 
-  function focusItem(i: number) {
-    active = i
-    queueMicrotask(() => listEl?.querySelector<HTMLElement>(`[data-mi="${i}"]`)?.focus())
-  }
-  function move(delta: number) {
-    if (!focusable.length) return
-    const pos = focusable.indexOf(active)
-    const next = focusable[(pos + delta + focusable.length) % focusable.length]
-    if (next != null) { openSub = -1; focusItem(next) }
-  }
-  function choose(item: MenuItem) {
-    if (item.disabled || item.separator) return
-    if (item.children?.length) { openSub = items.indexOf(item); return }
-    item.onSelect?.()
-    onselect(item)
-    onclose()
-  }
-  function onKeydown(e: KeyboardEvent, i: number) {
-    const item = items[i]
-    const rtl = dir === 'rtl'
-    // Open this item's submenu (opposite key under rtl).
-    const openThis = () => { if (item?.children?.length) { e.preventDefault(); openSub = i } }
-    // Collapse just THIS list back into its parent item (opposite key under
-    // rtl) - `oncollapse` is local to this nesting level, unlike `onclose`.
-    const collapseThis = () => { if (submenu) { e.preventDefault(); oncollapse?.() } }
-    switch (e.key) {
-      case 'ArrowDown': e.preventDefault(); move(1); break
-      case 'ArrowUp': e.preventDefault(); move(-1); break
-      case 'Home': e.preventDefault(); focusItem(focusable[0] ?? 0); break
-      case 'End': e.preventDefault(); focusItem(focusable.at(-1) ?? 0); break
-      case 'ArrowRight': (rtl ? collapseThis : openThis)(); break
-      case 'ArrowLeft': (rtl ? openThis : collapseThis)(); break
-      case 'Enter':
-      case ' ': e.preventDefault(); if (item) choose(item); break
-      case 'Escape': e.preventDefault(); onclose(); break
-      // Tab leaves the menu entirely (WAI-ARIA menu button pattern): close the
-      // whole tree rather than trapping focus inside a portalled panel.
-      case 'Tab': onclose(); break
-    }
-  }
+  // Roving focus, submenu open/collapse and the full keyboard contract live in
+  // the shared headless core; this component only renders + drives real DOM
+  // focus (the core stays DOM-free). See createMenu.svelte.ts.
+  const menu = createMenu({
+    items: () => items,
+    onSelect: (item) => onselect(item),
+    onClose: () => onclose(),
+    submenu: () => submenu,
+    onCollapse: () => oncollapse?.(),
+    dir: () => dir,
+    focusItem: (i) => queueMicrotask(() => listEl?.querySelector<HTMLElement>(`[data-mi="${i}"]`)?.focus()),
+  })
 </script>
 
 <!-- svelte-ignore a11y_no_noninteractive_element_interactions -->
-<div bind:this={listEl} class="sv-menu__list" class:is-submenu={submenu} role="menu">
+<div bind:this={listEl} class="sv-menu__list" class:is-submenu={submenu} {...menu.listProps()}>
   {#each items as item, i (i)}
     {#if item.separator}
       <div class="sv-menu__sep" role="separator"></div>
@@ -104,30 +65,21 @@
         <button
           type="button"
           class="sv-menu__item"
-          class:is-active={active === i}
-          data-mi={i}
-          role="menuitem"
-          aria-haspopup={item.children?.length ? 'menu' : undefined}
-          aria-expanded={item.children?.length ? openSub === i : undefined}
-          aria-disabled={item.disabled || undefined}
-          disabled={item.disabled}
-          tabindex={active === i || (active === -1 && i === focusable[0]) ? 0 : -1}
-          onpointerenter={() => { if (!item.disabled) { active = i; openSub = item.children?.length ? i : -1 } }}
-          onkeydown={(e) => onKeydown(e, i)}
-          onclick={() => choose(item)}
+          class:is-active={menu.isActive(i)}
+          {...menu.itemProps(i)}
         >
           <span class="sv-menu__icon">{#if item.icon}{@render item.icon()}{/if}</span>
           <span class="sv-menu__label">{item.label}</span>
           {#if item.shortcut}<span class="sv-menu__shortcut">{item.shortcut}</span>{/if}
           {#if item.children?.length}<svg class="sv-menu__chev" viewBox="0 0 24 24" width="13" height="13" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><path d="m9 18 6-6-6-6" /></svg>{/if}
         </button>
-        {#if item.children?.length && openSub === i}
+        {#if item.children?.length && menu.isSubOpen(i)}
           <div class="sv-menu__flyout">
             <Self
               items={item.children}
               {onclose}
               {onselect}
-              oncollapse={() => { openSub = -1; focusItem(i) }}
+              oncollapse={() => menu.focus(i)}
               {dir}
               submenu
             />

package/dist/SvMenuList.svelte.d.ts

@@ -1,17 +1,6 @@
-import type { Snippet } from 'svelte';
-export type MenuItem = {
-    /** Item text. Omit + set `separator` for a divider. */
-    label?: string;
-    separator?: boolean;
-    icon?: Snippet;
-    /** Right-aligned hint, e.g. a keyboard shortcut. */
-    shortcut?: string;
-    disabled?: boolean;
-    /** Nested submenu items (renders a flyout). */
-    children?: MenuItem[];
-    onSelect?: () => void;
-};
+export type { MenuItem } from './menu-item';
 import { type EditorDir } from './editor-contract';
+import type { MenuItem } from './menu-item';
 type $$ComponentProps = {
     items: ReadonlyArray<MenuItem>;
     /** Close the WHOLE menu (a leaf was chosen, Escape, or outside-click). */

package/dist/SvModal.svelte

@@ -15,9 +15,7 @@
   import type { Snippet } from 'svelte'
   import { portalToBody } from './popover'
   import { nextEditorId } from './editor-contract'
-  import { createFocusTrap } from './a11y/focus-trap'
-  import { lockScroll } from './a11y/scroll-lock'
-  import { createDismissableLayer } from './a11y/dismissable'
+  import { createOverlay } from './createOverlay.svelte'
 
   type Props = {
     open?: boolean
@@ -55,28 +53,16 @@
 
   function close() { open = false; onClose?.() }
 
-  // Reset transient drag/resize each time it opens, then hand focus, scroll-lock
-  // and Escape/backdrop dismissal to the shared a11y primitives (one tested
-  // implementation, and nested overlays close top-first via the layer stack).
-  $effect(() => {
-    if (!open || !dialogEl) return
-    drag = { x: 0, y: 0 }
-    box = null
-    const trap = createFocusTrap(dialogEl)
-    trap.activate()
-    const unlockScroll = lockScroll()
-    const layer = createDismissableLayer({
-      element: () => dialogEl,
-      onDismiss: (reason) => {
-        if (reason === 'escape' ? closeOnEsc : closeOnBackdrop) close()
-      },
-    })
-    layer.activate()
-    return () => {
-      layer.release()
-      unlockScroll()
-      trap.release()
-    }
+  // Focus trap + scroll lock + Escape/backdrop dismissal come from the shared
+  // headless overlay core; this component resets its transient drag/resize on
+  // open and renders the panel. See createOverlay.svelte.ts.
+  const overlay = createOverlay({
+    open: () => open,
+    getDialog: () => dialogEl,
+    onClose: close,
+    closeOnEsc: () => closeOnEsc,
+    closeOnBackdrop: () => closeOnBackdrop,
+    onOpen: () => { drag = { x: 0, y: 0 }; box = null },
   })
 
   // --- Drag (header) ---------------------------------------------------------
@@ -130,10 +116,7 @@
       bind:this={dialogEl}
       class="sv-modal sv-modal--{size}"
       class:is-resized={!!box}
-      role="dialog"
-      aria-modal="true"
-      aria-labelledby={title ? titleId : undefined}
-      tabindex="-1"
+      {...overlay.dialogProps({ labelledBy: title ? titleId : undefined })}
       style:transform={`translate(calc(-50% + ${drag.x}px), calc(-50% + ${drag.y}px))`}
       style:width={box ? `${box.w}px` : undefined}
       style:height={box ? `${box.h}px` : undefined}

package/dist/SvMultiSelect.svelte

@@ -178,6 +178,7 @@
     style:top={`${ms.rect.top}px`}
     style:left={`${ms.rect.left}px`}
     style:min-width={`${ms.rect.width}px`}
+    style:max-height={`${ms.rect.maxHeight}px`}
     onkeydown={ms.onPanelKeydown}
   >
     {#if searchable}

package/dist/SvNumberInput.svelte

@@ -31,7 +31,7 @@
   }
 
   let {
-    value = null,
+    value = $bindable<number | null>(null),
     onChange,
     min = -Infinity,
     max = Infinity,
@@ -62,7 +62,8 @@
 
   const num = createNumberInput({
     value: () => value,
-    onChange: (v) => onChange?.(v),
+    // Write `value` (so `bind:value` works) AND fire `onChange` (callback users).
+    onChange: (v) => { value = v; onChange?.(v) },
     min: () => min,
     max: () => max,
     step: () => step,
@@ -86,7 +87,7 @@
   <div class="sv-num sv-num--{size}" class:is-disabled={disabled} class:is-invalid={invalid}>
     <input class="sv-num__input" {...num.inputProps()} />
     {#if clearable && value != null && !disabled && !readonly}
-      <button type="button" class="sv-num__clear" aria-label="Clear" tabindex="-1" onclick={() => onChange?.(null)}>
+      <button type="button" class="sv-num__clear" aria-label="Clear" tabindex="-1" onclick={() => { value = null; onChange?.(null) }}>
         <svg viewBox="0 0 24 24" width="13" height="13" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round"><path d="M6 6l12 12M18 6L6 18" /></svg>
       </button>
     {/if}

package/dist/SvNumberInput.svelte.d.ts

@@ -15,6 +15,6 @@ type Props = SvEditorProps & {
     /** Show a clear (x) button when there is a value. */
     clearable?: boolean;
 };
-declare const SvNumberInput: import("svelte").Component<Props, {}, "">;
+declare const SvNumberInput: import("svelte").Component<Props, {}, "value">;
 type SvNumberInput = ReturnType<typeof SvNumberInput>;
 export default SvNumberInput;

package/dist/SvPagination.svelte

@@ -9,7 +9,7 @@
    * <SvPagination page={p} pageCount={20} onChange={(n) => (p = n)} />
    * ```
    */
-  import { paginationRange } from './paginate'
+  import { createPagination } from './createPagination'
 
   type Props = {
     /** 1-based current page. */
@@ -38,23 +38,26 @@
     ariaLabel = 'Pagination',
   }: Props = $props()
 
-  const items = $derived(paginationRange({ page, pageCount, siblingCount, boundaryCount }))
-  const go = (p: number) => {
-    if (disabled) return
-    const next = Math.min(Math.max(p, 1), pageCount)
-    if (next !== page) onChange?.(next)
-  }
+  // Page-range math + navigation live in the shared headless core.
+  const pg = createPagination({
+    page: () => page,
+    pageCount: () => pageCount,
+    onChange,
+    siblingCount: () => siblingCount,
+    boundaryCount: () => boundaryCount,
+    disabled: () => disabled,
+  })
 </script>
 
-<nav class="sv-pg sv-pg--{size}" aria-label={ariaLabel}>
+<nav class="sv-pg sv-pg--{size}" {...pg.navProps(ariaLabel)}>
   <ul class="sv-pg__list">
     {#if showFirstLast}
-      <li><button type="button" class="sv-pg__btn" aria-label="First page" onclick={() => go(1)} disabled={disabled || page <= 1}>&laquo;</button></li>
+      <li><button type="button" class="sv-pg__btn" {...pg.firstProps()}>&laquo;</button></li>
     {/if}
     {#if showPrevNext}
-      <li><button type="button" class="sv-pg__btn" aria-label="Previous page" onclick={() => go(page - 1)} disabled={disabled || page <= 1}>&lsaquo;</button></li>
+      <li><button type="button" class="sv-pg__btn" {...pg.prevProps()}>&lsaquo;</button></li>
     {/if}
-    {#each items as it, i (typeof it === 'number' ? `p${it}` : `${it}-${i}`)}
+    {#each pg.items as it, i (typeof it === 'number' ? `p${it}` : `${it}-${i}`)}
       {#if it === 'ellipsis-left' || it === 'ellipsis-right'}
         <li><span class="sv-pg__ellipsis" aria-hidden="true">&hellip;</span></li>
       {:else}
@@ -62,20 +65,17 @@
           <button
             type="button"
             class="sv-pg__btn"
-            class:is-active={it === page}
-            aria-current={it === page ? 'page' : undefined}
-            aria-label={`Page ${it}`}
-            {disabled}
-            onclick={() => go(it)}
+            class:is-active={pg.isActive(it)}
+            {...pg.pageButtonProps(it)}
           >{it}</button>
         </li>
       {/if}
     {/each}
     {#if showPrevNext}
-      <li><button type="button" class="sv-pg__btn" aria-label="Next page" onclick={() => go(page + 1)} disabled={disabled || page >= pageCount}>&rsaquo;</button></li>
+      <li><button type="button" class="sv-pg__btn" {...pg.nextProps()}>&rsaquo;</button></li>
     {/if}
     {#if showFirstLast}
-      <li><button type="button" class="sv-pg__btn" aria-label="Last page" onclick={() => go(pageCount)} disabled={disabled || page >= pageCount}>&raquo;</button></li>
+      <li><button type="button" class="sv-pg__btn" {...pg.lastProps()}>&raquo;</button></li>
     {/if}
   </ul>
 </nav>

package/dist/SvPasswordInput.svelte

@@ -31,7 +31,7 @@
   }
 
   let {
-    value = '',
+    value = $bindable(''),
     onChange,
     placeholder,
     disabled = false,
@@ -58,7 +58,8 @@
 
   const pw = createPasswordInput({
     value: () => value,
-    onChange: (v) => onChange?.(v),
+    // Write `value` (so `bind:value` works) AND fire `onChange` (callback users).
+    onChange: (v) => { value = v; onChange?.(v) },
     placeholder: () => placeholder,
     disabled: () => disabled,
     readonly: () => readonly,

package/dist/SvPasswordInput.svelte.d.ts

@@ -20,6 +20,6 @@ type Props = SvEditorProps & {
     /** Override the built-in strings (reveal toggle + strength labels). */
     messages?: Partial<PasswordMessages>;
 };
-declare const SvPasswordInput: import("svelte").Component<Props, {}, "">;
+declare const SvPasswordInput: import("svelte").Component<Props, {}, "value">;
 type SvPasswordInput = ReturnType<typeof SvPasswordInput>;
 export default SvPasswordInput;

package/dist/SvPhoneInput.svelte

@@ -27,7 +27,7 @@
   }
 
   let {
-    value = '',
+    value = $bindable(''),
     onChange,
     country = 'US',
     disabled = false,
@@ -52,7 +52,8 @@
 
   const ph = createPhoneInput({
     value: () => value,
-    onChange: (v, parts) => onChange?.(v, parts),
+    // Write `value` (so `bind:value` works) AND fire `onChange` (callback users).
+    onChange: (v, parts) => { value = v; onChange?.(v, parts) },
     country: () => country,
     disabled: () => disabled,
     readonly: () => readonly,

package/dist/SvPhoneInput.svelte.d.ts

@@ -13,6 +13,6 @@ type Props = SvEditorProps & {
     /** Override the built-in strings (e.g. the country selector aria-label). */
     messages?: Partial<PhoneMessages>;
 };
-declare const SvPhoneInput: import("svelte").Component<Props, {}, "">;
+declare const SvPhoneInput: import("svelte").Component<Props, {}, "value">;
 type SvPhoneInput = ReturnType<typeof SvPhoneInput>;
 export default SvPhoneInput;

package/dist/SvPopover.svelte

@@ -49,7 +49,7 @@
 
   let anchorEl = $state<HTMLSpanElement | null>(null)
   let panelEl = $state<HTMLDivElement | null>(null)
-  let rect = $state<AnchoredRect>({ top: 0, left: 0, width: 0, openUpward: false })
+  let rect = $state<AnchoredRect>({ top: 0, left: 0, width: 0, openUpward: false, maxHeight: 0, availHeight: 0 })
 
   function setOpen(v: boolean) { if (v !== open) { open = v; onOpenChange?.(v) } }
   function toggle() { setOpen(!open) }

package/dist/SvStepper.svelte

@@ -14,6 +14,7 @@
    * ```
    */
   import type { StepItem } from './ui-app.types'
+  import { createStepper } from './createStepper'
 
   type Props = {
     steps: ReadonlyArray<StepItem>
@@ -27,22 +28,18 @@
 
   let { steps, current, onChange, linear = true, orientation = 'horizontal' }: Props = $props()
 
-  const statusOf = (i: number): 'complete' | 'active' | 'upcoming' =>
-    i < current ? 'complete' : i === current ? 'active' : 'upcoming'
-  const clickable = (i: number) => (linear ? i <= current : true)
-  const go = (i: number) => { if (clickable(i) && i !== current) onChange?.(i) }
+  // Status, clickability and navigation live in the shared headless core.
+  const st = createStepper({ count: () => steps.length, current: () => current, onChange, linear: () => linear })
 </script>
 
 <ol class="sv-step sv-step--{orientation}">
   {#each steps as step, i (i)}
-    {@const status = statusOf(i)}
-    <li class="sv-step__item is-{status}" class:is-clickable={clickable(i)}>
+    {@const status = st.statusOf(i)}
+    <li class="sv-step__item is-{status}" class:is-clickable={st.clickable(i)}>
       <button
         type="button"
         class="sv-step__btn"
-        aria-current={status === 'active' ? 'step' : undefined}
-        disabled={!clickable(i)}
-        onclick={() => go(i)}
+        {...st.stepButtonProps(i)}
       >
         <span class="sv-step__marker" aria-hidden="true">
           {#if status === 'complete'}✓{:else}{i + 1}{/if}

package/dist/SvTagsInput.svelte

@@ -27,7 +27,7 @@
   }
 
   let {
-    value = [],
+    value = $bindable<string[]>([]),
     onChange,
     placeholder = 'Add tag…',
     disabled = false,
@@ -51,7 +51,8 @@
 
   const ti = createTagsInput({
     value: () => value,
-    onChange: (t) => onChange?.(t),
+    // Write `value` (so `bind:value` works) AND fire `onChange` (callback users).
+    onChange: (t) => { value = t; onChange?.(t) },
     disabled: () => disabled,
     unique: () => unique,
     max: () => max,

package/dist/SvTagsInput.svelte.d.ts

@@ -14,6 +14,6 @@ type Props = SvEditorProps & {
     /** Override the built-in strings (draft + remove aria-labels). */
     messages?: Partial<TagsMessages>;
 };
-declare const SvTagsInput: import("svelte").Component<Props, {}, "">;
+declare const SvTagsInput: import("svelte").Component<Props, {}, "value">;
 type SvTagsInput = ReturnType<typeof SvTagsInput>;
 export default SvTagsInput;

package/dist/SvTooltip.svelte

@@ -12,8 +12,8 @@
    */
   import type { Snippet } from 'svelte'
   import { portalToBody, popIn } from './popover'
-  import { nextEditorId } from './editor-contract'
   import { getFocusable } from './a11y/focus-trap'
+  import { createTooltip } from './createTooltip.svelte'
 
   type Props = {
     text: string
@@ -28,10 +28,12 @@
 
   let anchorEl = $state<HTMLSpanElement | null>(null)
   let tipEl = $state<HTMLDivElement | null>(null)
-  let open = $state(false)
   let pos = $state({ top: 0, left: 0, arrowX: 12 })
-  const tid = nextEditorId('sv-tip')
-  let showTimer: ReturnType<typeof setTimeout> | undefined
+
+  // Open state, show-delay and Escape-to-hide live in the shared headless core;
+  // this component owns only the DOM concerns (positioning + describedby merge).
+  const tip = createTooltip({ text: () => text, disabled: () => disabled, delay: () => delay })
+  const tid = tip.tipId
 
   function place() {
     if (!anchorEl) return
@@ -46,25 +48,16 @@
     pos = { top, left, arrowX }
   }
 
-  function show() {
-    if (disabled || !text) return
-    clearTimeout(showTimer)
-    showTimer = setTimeout(() => { open = true; queueMicrotask(place) }, delay)
-  }
-  function hide() { clearTimeout(showTimer); open = false }
-
+  // Reposition while open (and on scroll/resize). Escape-to-hide is the core's.
   $effect(() => {
-    if (!open) return
-    place()
+    if (!tip.open) return
+    queueMicrotask(place)
     const rp = () => place()
     window.addEventListener('scroll', rp, true)
     window.addEventListener('resize', rp)
-    const onKey = (e: KeyboardEvent) => { if (e.key === 'Escape') hide() }
-    document.addEventListener('keydown', onKey)
     return () => {
       window.removeEventListener('scroll', rp, true)
       window.removeEventListener('resize', rp)
-      document.removeEventListener('keydown', onKey)
     }
   })
 
@@ -75,7 +68,7 @@
   // announced. Mirror the id onto that child too, merging with (and later
   // restoring) any aria-describedby it already carries.
   $effect(() => {
-    if (!open || !anchorEl) return
+    if (!tip.open || !anchorEl) return
     const child = getFocusable(anchorEl)[0]
     if (!child) return
     const before = child.getAttribute('aria-describedby')
@@ -96,16 +89,12 @@
 <span
   bind:this={anchorEl}
   class="sv-tip__anchor"
-  aria-describedby={open ? tid : undefined}
-  onpointerenter={show}
-  onpointerleave={hide}
-  onfocusin={show}
-  onfocusout={hide}
+  {...tip.anchorProps()}
 >
   {@render children?.()}
 </span>
 
-{#if open}
+{#if tip.open}
   <div
     bind:this={tipEl}
     id={tid}

package/dist/SvTour.svelte

@@ -98,14 +98,34 @@
   })
 
   const POP_W = 300
+  // Measured popover height, so placement can keep the WHOLE popover on-screen
+  // (long content + tall targets used to push it off the top).
+  let popH = $state(200)
   const pop = $derived.by(() => {
     if (typeof window === 'undefined' || !rect) {
       return { top: '50%', left: '50%', transform: 'translate(-50%, -50%)', place: 'center' as const }
     }
-    const left = Math.max(12, Math.min(rect.left, window.innerWidth - POP_W - 12))
-    const below = window.innerHeight - rect.bottom
-    if (below > 190) return { top: `${rect.bottom + 10}px`, left: `${left}px`, transform: 'none', place: 'bottom' as const }
-    return { top: `${rect.top - 10}px`, left: `${left}px`, transform: 'translateY(-100%)', place: 'top' as const }
+    const vw = window.innerWidth
+    const vh = window.innerHeight
+    const gap = 12
+    const h = popH || 200
+    const clampTop = (t: number) => Math.max(gap, Math.min(t, vh - h - gap))
+    const clampLeft = (l: number) => Math.max(gap, Math.min(l, vw - POP_W - gap))
+    // Prefer directly below the target, then directly above - but only when the
+    // target is short enough to leave room for the whole popover.
+    if (vh - rect.bottom >= h + gap) {
+      return { top: `${rect.bottom + 10}px`, left: `${clampLeft(rect.left)}px`, transform: 'none', place: 'bottom' as const }
+    }
+    if (rect.top >= h + gap) {
+      return { top: `${clampTop(rect.top - 10 - h)}px`, left: `${clampLeft(rect.left)}px`, transform: 'none', place: 'top' as const }
+    }
+    // Tall target (a full-height rail / canvas / inspector): sit BESIDE it,
+    // vertically centred on the target, on whichever side has room.
+    const top = clampTop(rect.top + rect.height / 2 - h / 2)
+    if (vw - rect.right >= POP_W + gap) return { top: `${top}px`, left: `${rect.right + 10}px`, transform: 'none', place: 'center' as const }
+    if (rect.left >= POP_W + gap) return { top: `${top}px`, left: `${rect.left - POP_W - 10}px`, transform: 'none', place: 'center' as const }
+    // No side room either - centre horizontally (still fully visible).
+    return { top: `${top}px`, left: `${clampLeft((vw - POP_W) / 2)}px`, transform: 'none', place: 'center' as const }
   })
 </script>
 
@@ -125,6 +145,7 @@
 
     <div
       bind:this={popEl}
+      bind:clientHeight={popH}
       class="sv-tour__pop sv-tour__pop--{pop.place}"
       style:top={pop.top}
       style:left={pop.left}
@@ -133,6 +154,11 @@
       aria-modal="true"
       aria-label={step.title ?? 'Tour step'}
     >
+      {#if step.image}
+        <div class="sv-tour__media">
+          {#if /^(https?:|data:|\/)/.test(step.image)}<img class="sv-tour__img" src={step.image} alt="" />{:else}{@html step.image}{/if}
+        </div>
+      {/if}
       {#if step.title}<div class="sv-tour__title">{step.title}</div>{/if}
       <div class="sv-tour__body">{step.content}</div>
       <div class="sv-tour__foot">
@@ -163,6 +189,8 @@
   }
   @keyframes sv-tour-in { from { opacity: 0; transform: translateY(4px) } }
   :global(.sv-tour__pop--top) { animation: none; }
+  :global(.sv-tour__media) { margin: -2px -4px 12px; border-radius: 9px; overflow: hidden; line-height: 0; }
+  :global(.sv-tour__media svg), :global(.sv-tour__img) { display: block; width: 100%; height: auto; }
   :global(.sv-tour__title) { font-size: 14.5px; font-weight: 650; margin-bottom: 4px; }
   :global(.sv-tour__body) { font-size: 13px; line-height: 1.55; color: var(--sg-fg, #334155); }
   :global(.sv-tour__foot) { display: flex; align-items: center; justify-content: space-between; gap: 10px; margin-top: 14px; }

package/dist/SvTreeSelect.svelte

@@ -166,6 +166,7 @@
       aria-label={label ?? ariaLabel ?? 'Tree'}
       aria-activedescendant={ts.activeDescendant()}
       tabindex="0"
+      style:max-height={`${ts.rect.maxHeight}px`}
       onkeydown={ts.onPanelKeydown}
     >
       {#each rows as row, i (row.node.value)}