@svgrid/grid 1.2.33 → 2.0.0

package/src/SvTextInput.svelte

@@ -0,0 +1,115 @@
+<script lang="ts">
+  /**
+   * SvTextInput - the base single-line text editor on the shared editor contract
+   * (label / hint / error / RTL / a11y via SvField). Handles `text`, `email`,
+   * `url`, `tel` and `search`. As a grid cell editor it honours the interaction
+   * contract: Enter commits, Escape cancels. Parity: Smart `smart-input`.
+   */
+  import SvField from './SvField.svelte'
+  import { editorAria, nextEditorId, type SvEditorProps } from './editor-contract'
+
+  type Props = SvEditorProps & {
+    value?: string
+    onChange?: (value: string) => void
+    /** Commit + stop editing (Enter, or supplied by the grid in a cell). */
+    onCommit?: (value: string) => void
+    /** Cancel editing (Escape). */
+    onCancel?: () => void
+    placeholder?: string
+    type?: 'text' | 'email' | 'url' | 'tel' | 'search'
+    maxlength?: number
+    /** Show an inline clear (x) button when non-empty. */
+    clearable?: boolean
+    autocomplete?: AutoFill
+    /** Autofocus + select on mount (used when mounted as a cell editor). */
+    autofocus?: boolean
+  }
+
+  let {
+    value = $bindable(''),
+    onChange,
+    onCommit,
+    onCancel,
+    placeholder,
+    disabled = false,
+    readonly = false,
+    type = 'text',
+    maxlength,
+    clearable = false,
+    name,
+    size = 'md',
+    ariaLabel,
+    invalid = false,
+    required = false,
+    error,
+    label,
+    hint,
+    dir,
+    id,
+    autocomplete,
+    autofocus = false,
+  }: Props = $props()
+
+  const autoId = nextEditorId('sv-text')
+  const uid = $derived(id ?? autoId)
+
+  // Write `value` (so `bind:value` works) AND fire `onChange` (callback users).
+  function set(v: string) {
+    value = v
+    onChange?.(v)
+  }
+  function onInput(e: Event) {
+    set((e.currentTarget as HTMLInputElement).value)
+  }
+  function onKeydown(e: KeyboardEvent) {
+    if (e.key === 'Enter') onCommit?.(value)
+    else if (e.key === 'Escape') onCancel?.()
+  }
+  function mountFocus(node: HTMLInputElement) {
+    if (autofocus) { node.focus(); node.select() }
+  }
+</script>
+
+<SvField id={uid} {label} {hint} {error} {required} {dir}>
+  <div class="sv-text sv-text--{size}" class:is-disabled={disabled}>
+    <div class="sv-text__field" class:is-invalid={invalid}>
+      <input
+        use:mountFocus
+        class="sv-text__input"
+        {type}
+        {value}
+        {placeholder}
+        {disabled}
+        {readonly}
+        {maxlength}
+        {autocomplete}
+        oninput={onInput}
+        onkeydown={onKeydown}
+        {...editorAria({ id: uid, invalid, required, error, hint, ariaLabel })}
+      />
+      {#if clearable && value && !disabled && !readonly}
+        <button class="sv-text__clear" type="button" tabindex="-1" aria-label="Clear" onclick={() => set('')}>&times;</button>
+      {/if}
+    </div>
+    {#if name}<input type="hidden" {name} value={value} />{/if}
+  </div>
+</SvField>
+
+<style>
+  .sv-text { --_accent: var(--sg-accent, #2563eb); display: inline-flex; flex-direction: column; width: 220px; }
+  .sv-text.is-disabled { opacity: 0.6; }
+  .sv-text__field {
+    display: flex; align-items: center;
+    background: var(--sg-input-bg, #fff); color: var(--sg-fg, #0f172a);
+    border: 1px solid var(--sg-input-border, var(--sg-border, #cbd5e1)); border-radius: var(--sg-radius, 8px);
+  }
+  .sv-text__field:focus-within { border-color: var(--_accent); box-shadow: 0 0 0 2px color-mix(in srgb, var(--_accent) 22%, transparent); }
+  .sv-text__field.is-invalid { border-color: var(--sg-danger, #dc2626); }
+  .sv-text__field.is-invalid:focus-within { box-shadow: 0 0 0 2px color-mix(in srgb, var(--sg-danger, #dc2626) 22%, transparent); }
+  .sv-text__input { flex: 1; min-width: 0; border: 0; background: none; outline: none; color: inherit; font: inherit; padding: 0 10px; }
+  .sv-text--sm .sv-text__field { height: 28px; font-size: 12px; }
+  .sv-text--md .sv-text__field { height: 34px; font-size: 13px; }
+  .sv-text--lg .sv-text__field { height: 40px; font-size: 15px; }
+  .sv-text__clear { display: grid; place-items: center; width: 28px; align-self: stretch; background: none; border: 0; color: var(--sg-muted, #64748b); cursor: pointer; font-size: 17px; line-height: 1; }
+  .sv-text__clear:hover { color: var(--sg-fg, #0f172a); }
+</style>

package/src/SvTimePicker.svelte

@@ -11,8 +11,13 @@
    * and ARIA; this component keeps the DOM-bound pointer capture + hit-testing.
    * All visuals come from `--sg-*` tokens so every theme applies for free.
    */
+  import { resolveMessages, type EditorDir } from './editor-contract'
   import { createTimePicker, type TimeValue, type TimeFormat, type TimeSelection } from './createTimePicker.svelte'
 
+  /** User-facing strings (localizable via `messages`). */
+  type TimeMessages = { label: string; am: string; pm: string; now: string }
+  const DEFAULT_MESSAGES: TimeMessages = { label: 'Time picker', am: 'AM', pm: 'PM', now: 'Now' }
+
   type Props = {
     /** Date, "HH:MM[:SS]" string, or epoch ms. */
     value?: TimeValue
@@ -29,6 +34,10 @@
     name?: string
     /** Which dial opens first. */
     selection?: TimeSelection
+    /** Text direction (rtl mirrors layout; auto/undefined inherits). */
+    dir?: EditorDir
+    /** Override the built-in strings (group label + AM/PM/Now). */
+    messages?: Partial<TimeMessages>
   }
 
   let {
@@ -42,8 +51,13 @@
     readonly = false,
     name,
     selection = 'hour',
+    dir,
+    messages,
   }: Props = $props()
 
+  const M = $derived(resolveMessages(DEFAULT_MESSAGES, messages))
+  const resolvedDir = $derived(dir === 'ltr' || dir === 'rtl' ? dir : undefined)
+
   // The headless core owns all state, geometry, keyboard + ARIA. Reactive inputs
   // are getters; callbacks are closures.
   const tp = createTimePicker({
@@ -93,7 +107,7 @@
   }
 </script>
 
-<div class="sv-tp" class:sv-tp--disabled={disabled} role="group" aria-label="Time picker">
+<div class="sv-tp" class:sv-tp--disabled={disabled} role="group" aria-label={M.label} dir={resolvedDir}>
   <div class="sv-tp__head">
     <button class="sv-tp__seg" class:is-active={tp.selection === 'hour'} {...tp.segProps('hour')}>
       {String(tp.displayHour).padStart(2, '0')}
@@ -104,8 +118,8 @@
     </button>
     {#if tp.is12}
       <div class="sv-tp__ampm">
-        <button class:is-active={!tp.isPm} {...tp.ampmProps(false)}>AM</button>
-        <button class:is-active={tp.isPm} {...tp.ampmProps(true)}>PM</button>
+        <button class:is-active={!tp.isPm} {...tp.ampmProps(false)}>{M.am}</button>
+        <button class:is-active={tp.isPm} {...tp.ampmProps(true)}>{M.pm}</button>
       </div>
     {/if}
   </div>
@@ -139,7 +153,7 @@
 
   {#if footer}
     <div class="sv-tp__footer">
-      <button class="sv-tp__now" {...tp.nowProps()}>Now</button>
+      <button class="sv-tp__now" {...tp.nowProps()}>{M.now}</button>
     </div>
   {/if}
 
@@ -171,7 +185,7 @@
   }
   .sv-tp__seg.is-active { color: var(--_accent); background: color-mix(in srgb, var(--_accent) 12%, transparent); }
   .sv-tp__colon { font-size: 28px; font-weight: 700; color: var(--_muted); }
-  .sv-tp__ampm { display: flex; flex-direction: column; margin-left: 8px; gap: 2px; }
+  .sv-tp__ampm { display: flex; flex-direction: column; margin-inline-start: 8px; gap: 2px; }
   .sv-tp__ampm button {
     font-size: 11px; font-weight: 700; padding: 3px 8px;
     background: none; border: 1px solid var(--_border); border-radius: 6px; color: var(--_muted); cursor: pointer;

package/src/SvTimeline.svelte

@@ -0,0 +1,75 @@
+<script lang="ts" module>
+  export type { TimelineItem } from './ui-app.types'
+</script>
+
+<script lang="ts">
+  /**
+   * SvTimeline - a vertical activity / history feed: a connecting line with a
+   * marker (colour + optional glyph) per entry, and a title / time / description.
+   * Data-driven via `items`, with an optional `item` snippet for custom content.
+   * Theme-driven. Parity: Smart timeline.
+   *
+   * ```svelte
+   * <SvTimeline items={[
+   *   { title: 'Order placed', time: '09:12', color: '#16a34a' },
+   *   { title: 'Shipped', time: '14:40', description: 'Left the warehouse' },
+   * ]} />
+   * ```
+   */
+  import type { Snippet } from 'svelte'
+  import type { TimelineItem } from './ui-app.types'
+
+  type Props = {
+    items: ReadonlyArray<TimelineItem>
+    /** Render custom content per entry (receives the item). */
+    item?: Snippet<[TimelineItem]>
+  }
+
+  let { items, item }: Props = $props()
+</script>
+
+<ol class="sv-timeline">
+  {#each items as it, i (it.id ?? i)}
+    <li class="sv-timeline__item">
+      <div class="sv-timeline__rail">
+        <span class="sv-timeline__marker" style:--c={it.color}>
+          {#if it.icon}<span class="sv-timeline__glyph">{it.icon}</span>{/if}
+        </span>
+      </div>
+      <div class="sv-timeline__content">
+        {#if item}
+          {@render item(it)}
+        {:else}
+          <div class="sv-timeline__row">
+            <span class="sv-timeline__title">{it.title}</span>
+            {#if it.time}<span class="sv-timeline__time">{it.time}</span>{/if}
+          </div>
+          {#if it.description}<p class="sv-timeline__desc">{it.description}</p>{/if}
+        {/if}
+      </div>
+    </li>
+  {/each}
+</ol>
+
+<style>
+  .sv-timeline { list-style: none; margin: 0; padding: 0; color: var(--sg-fg, #0f172a); }
+  .sv-timeline__item { display: grid; grid-template-columns: 22px 1fr; gap: 10px; }
+  .sv-timeline__rail { display: flex; flex-direction: column; align-items: center; }
+  .sv-timeline__marker {
+    --c: var(--sg-accent, #2563eb);
+    flex: none; width: 14px; height: 14px; margin-top: 2px; border-radius: 50%;
+    display: grid; place-items: center; font-size: 8px; color: var(--sg-on-accent, #fff);
+    background: var(--c); box-shadow: 0 0 0 3px color-mix(in srgb, var(--c) 18%, transparent);
+  }
+  .sv-timeline__glyph { line-height: 1; }
+  /* The connecting line: grows to fill the rail between markers. */
+  .sv-timeline__item:not(:last-child) .sv-timeline__rail::after {
+    content: ''; flex: 1; width: 2px; margin: 3px 0 -2px; background: var(--sg-border, #e2e8f0); border-radius: 1px;
+  }
+  .sv-timeline__content { padding-bottom: 16px; min-width: 0; }
+  .sv-timeline__item:last-child .sv-timeline__content { padding-bottom: 0; }
+  .sv-timeline__row { display: flex; align-items: baseline; gap: 10px; }
+  .sv-timeline__title { font-size: 13.5px; font-weight: 600; }
+  .sv-timeline__time { margin-inline-start: auto; flex: none; font-size: 11.5px; color: var(--sg-muted, #94a3b8); font-variant-numeric: tabular-nums; }
+  .sv-timeline__desc { margin: 2px 0 0; font-size: 12.5px; color: var(--sg-muted, #64748b); line-height: 1.5; }
+</style>

package/src/SvToaster.svelte

@@ -0,0 +1,124 @@
+<script lang="ts">
+  /**
+   * SvToaster - renders the shared toast queue (see `toast-store`). Mount ONCE
+   * near the app root; call `toast()` from anywhere to push notifications. The
+   * container is an `aria-live` region as a visual backstop, though each toast
+   * is also announced through the shared live region by the store.
+   *
+   * ```svelte
+   * <SvToaster position="bottom-right" />
+   * ```
+   */
+  import { portalToBody } from './popover'
+  import { toastStore, dismissToast, pauseToast, resumeToast, type Toast } from './toast-store.svelte'
+
+  type Position =
+    | 'top-left' | 'top-center' | 'top-right'
+    | 'bottom-left' | 'bottom-center' | 'bottom-right'
+
+  type Props = {
+    /** Corner/edge the stack anchors to. Default 'bottom-right'. */
+    position?: Position
+    /** Max toasts shown at once (older ones stay queued in the store). */
+    max?: number
+  }
+
+  let { position = 'bottom-right', max = 5 }: Props = $props()
+
+  const visible = $derived(toastStore.toasts.slice(-max))
+  const icon = (v: Toast['variant']) =>
+    v === 'success' ? '✓' : v === 'error' ? '✕' : v === 'warning' ? '⚠' : 'ℹ'
+
+  // Swipe-to-dismiss: drag a toast sideways past ~60px to dismiss it.
+  let drag = $state<{ id: number; startX: number; dx: number } | null>(null)
+  function onDown(e: PointerEvent, id: number) {
+    drag = { id, startX: e.clientX, dx: 0 }
+    ;(e.currentTarget as HTMLElement).setPointerCapture?.(e.pointerId)
+    pauseToast(id)
+  }
+  function onMove(e: PointerEvent) {
+    if (drag) drag = { ...drag, dx: e.clientX - drag.startX }
+  }
+  function onUp(id: number) {
+    if (!drag || drag.id !== id) return
+    const dx = drag.dx
+    drag = null
+    if (Math.abs(dx) > 60) dismissToast(id)
+    else resumeToast(id)
+  }
+  const dragDx = (id: number) => (drag?.id === id ? drag.dx : 0)
+</script>
+
+<div class="sv-toaster sv-toaster--{position}" use:portalToBody role="region" aria-label="Notifications">
+  {#each visible as t (t.id)}
+    <!-- svelte-ignore a11y_no_static_element_interactions -->
+    <div
+      class="sv-toast sv-toast--{t.variant}"
+      class:is-dragging={drag?.id === t.id}
+      role={t.variant === 'error' || t.variant === 'warning' ? 'alert' : 'status'}
+      style:transform={dragDx(t.id) ? `translateX(${dragDx(t.id)}px)` : undefined}
+      style:opacity={dragDx(t.id) ? 1 - Math.min(Math.abs(dragDx(t.id)) / 160, 0.7) : undefined}
+      onmouseenter={() => pauseToast(t.id)}
+      onmouseleave={() => resumeToast(t.id)}
+      onfocusin={() => pauseToast(t.id)}
+      onfocusout={() => resumeToast(t.id)}
+      onpointerdown={(e) => onDown(e, t.id)}
+      onpointermove={onMove}
+      onpointerup={() => onUp(t.id)}
+      onpointercancel={() => onUp(t.id)}
+    >
+      <span class="sv-toast__icon" aria-hidden="true">{icon(t.variant)}</span>
+      <div class="sv-toast__content">
+        {#if t.title}<div class="sv-toast__title">{t.title}</div>{/if}
+        <div class="sv-toast__msg">{t.message}</div>
+      </div>
+      {#if t.dismissible}
+        <button type="button" class="sv-toast__x" aria-label="Dismiss" onclick={() => dismissToast(t.id)}>&times;</button>
+      {/if}
+    </div>
+  {/each}
+</div>
+
+<style>
+  :global(.sv-toaster) {
+    position: fixed; z-index: 2147483001; display: flex; flex-direction: column; gap: 8px;
+    padding: 16px; max-width: min(92vw, 380px); pointer-events: none;
+  }
+  :global(.sv-toaster--top-left) { top: 0; left: 0; }
+  :global(.sv-toaster--top-center) { top: 0; left: 50%; transform: translateX(-50%); align-items: center; }
+  :global(.sv-toaster--top-right) { top: 0; right: 0; }
+  :global(.sv-toaster--bottom-left) { bottom: 0; left: 0; flex-direction: column-reverse; }
+  :global(.sv-toaster--bottom-center) { bottom: 0; left: 50%; transform: translateX(-50%); align-items: center; flex-direction: column-reverse; }
+  :global(.sv-toaster--bottom-right) { bottom: 0; right: 0; flex-direction: column-reverse; }
+
+  :global(.sv-toast) {
+    pointer-events: auto;
+    display: flex; align-items: flex-start; gap: 10px; width: 100%; box-sizing: border-box;
+    padding: 11px 12px; border-radius: 10px; font-size: 13px; line-height: 1.45;
+    background: var(--sg-bg, #fff); color: var(--sg-fg, #0f172a);
+    border: 1px solid var(--sg-border, #e2e8f0);
+    border-inline-start: 3px solid var(--_accent, var(--sg-accent, #2563eb));
+    box-shadow: 0 12px 32px -12px rgba(15, 23, 42, 0.4);
+    animation: sv-toast-in 0.18s cubic-bezier(0.16, 1, 0.3, 1) both;
+    transition: transform 0.2s ease, opacity 0.2s ease;
+    touch-action: pan-y; /* let vertical scroll through; capture horizontal swipe */
+  }
+  :global(.sv-toast.is-dragging) { transition: none; cursor: grabbing; user-select: none; }
+  @keyframes sv-toast-in { from { opacity: 0; transform: translateY(6px) scale(0.98) } to { opacity: 1 } }
+  @media (prefers-reduced-motion: reduce) { :global(.sv-toast) { animation: none } }
+
+  :global(.sv-toast--success) { --_accent: var(--sg-success, #16a34a); }
+  :global(.sv-toast--error) { --_accent: var(--sg-danger, #dc2626); }
+  :global(.sv-toast--warning) { --_accent: var(--sg-warning, #f59e0b); }
+  :global(.sv-toast--info) { --_accent: var(--sg-accent, #2563eb); }
+
+  :global(.sv-toast__icon) { flex: none; width: 18px; height: 18px; display: grid; place-items: center; color: var(--_accent); font-weight: 700; }
+  :global(.sv-toast__content) { flex: 1; min-width: 0; }
+  :global(.sv-toast__title) { font-weight: 650; margin-bottom: 1px; }
+  :global(.sv-toast__msg) { color: var(--sg-fg, #0f172a); overflow-wrap: anywhere; }
+  :global(.sv-toast__x) {
+    flex: none; width: 22px; height: 22px; display: grid; place-items: center; margin: -2px -2px 0 0;
+    background: none; border: 0; color: var(--sg-muted, #64748b); cursor: pointer; border-radius: 5px; font-size: 17px; line-height: 1;
+  }
+  :global(.sv-toast__x:hover) { background: var(--sg-row-hover-bg, #f1f5f9); color: var(--sg-fg, #0f172a); }
+</style>

package/src/SvToaster.test.ts

@@ -0,0 +1,63 @@
+/**
+ * Component tests for SvToaster: renders the queue, and swipe-to-dismiss.
+ */
+import { afterEach, describe, expect, it } from 'vitest'
+import { mount, unmount, flushSync } from 'svelte'
+import SvToaster from './SvToaster.svelte'
+import { toast, clearToasts, toastStore } from './toast-store.svelte'
+
+function mountToaster() {
+  const target = document.createElement('div')
+  document.body.appendChild(target)
+  const app = mount(SvToaster, { target, props: {} })
+  flushSync()
+  return { destroy: () => { unmount(app); target.remove() } }
+}
+
+const toastEl = () => document.body.querySelector<HTMLElement>('.sv-toast')
+
+afterEach(() => {
+  clearToasts()
+  document.body.innerHTML = ''
+})
+
+describe('SvToaster', () => {
+  it('renders a queued toast', () => {
+    const { destroy } = mountToaster()
+    try {
+      toast('Saved', { duration: 0 })
+      flushSync()
+      expect(toastEl()).not.toBeNull()
+      expect(toastEl()!.textContent).toContain('Saved')
+    } finally { destroy() }
+  })
+
+  it('swiping a toast past the threshold dismisses it', () => {
+    const { destroy } = mountToaster()
+    try {
+      toast('Swipe me', { duration: 0 })
+      flushSync()
+      const el = toastEl()!
+      el.dispatchEvent(new MouseEvent('pointerdown', { bubbles: true, clientX: 100 }))
+      el.dispatchEvent(new MouseEvent('pointermove', { bubbles: true, clientX: 220 })) // dx 120 > 60
+      el.dispatchEvent(new MouseEvent('pointerup', { bubbles: true, clientX: 220 }))
+      flushSync()
+      expect(toastStore.toasts).toHaveLength(0)
+      expect(toastEl()).toBeNull()
+    } finally { destroy() }
+  })
+
+  it('a small swipe does not dismiss', () => {
+    const { destroy } = mountToaster()
+    try {
+      toast('Keep me', { duration: 0 })
+      flushSync()
+      const el = toastEl()!
+      el.dispatchEvent(new MouseEvent('pointerdown', { bubbles: true, clientX: 100 }))
+      el.dispatchEvent(new MouseEvent('pointermove', { bubbles: true, clientX: 130 })) // dx 30 < 60
+      el.dispatchEvent(new MouseEvent('pointerup', { bubbles: true, clientX: 130 }))
+      flushSync()
+      expect(toastStore.toasts).toHaveLength(1)
+    } finally { destroy() }
+  })
+})

package/src/SvToggleButton.svelte

@@ -4,18 +4,34 @@
    * Parity: Smart `smart-toggle-button`. Controlled via `pressed` + `onChange`.
    */
   import type { Snippet } from 'svelte'
+  import SvField from './SvField.svelte'
+  import { nextEditorId, type SvEditorProps } from './editor-contract'
   import { createToggle } from './createToggle.svelte'
 
-  type Props = {
+  type Props = SvEditorProps & {
     pressed?: boolean
     onChange?: (pressed: boolean) => void
-    disabled?: boolean
-    size?: 'sm' | 'md' | 'lg'
-    ariaLabel?: string
     children?: Snippet
   }
 
-  let { pressed = false, onChange, disabled = false, size = 'md', ariaLabel, children }: Props = $props()
+  let {
+    pressed = false,
+    onChange,
+    disabled = false,
+    size = 'md',
+    ariaLabel,
+    invalid = false,
+    required = false,
+    error,
+    label,
+    hint,
+    dir,
+    id,
+    children,
+  }: Props = $props()
+
+  const autoId = nextEditorId('sv-toggle')
+  const uid = $derived(id ?? autoId)
 
   // The styled toggle is just a renderer over the headless core.
   const t = createToggle({
@@ -23,16 +39,24 @@
     onChange: (v) => onChange?.(v),
     disabled: () => disabled,
     ariaLabel: () => ariaLabel,
+    id: () => uid,
+    invalid: () => invalid,
+    required: () => required,
+    error: () => error,
+    hint: () => hint,
   })
 </script>
 
-<button
-  class="sv-toggle sv-toggle--{size}"
-  class:is-pressed={pressed}
-  {...t.buttonProps()}
->
-  {#if children}{@render children()}{/if}
-</button>
+<SvField id={uid} {label} {hint} {error} {required} {dir}>
+  <button
+    class="sv-toggle sv-toggle--{size}"
+    class:is-pressed={pressed}
+    class:is-invalid={invalid}
+    {...t.buttonProps()}
+  >
+    {#if children}{@render children()}{/if}
+  </button>
+</SvField>
 
 <style>
   .sv-toggle {
@@ -53,5 +77,6 @@
     background: var(--_accent); color: var(--sg-on-accent, #fff); border-color: var(--_accent);
   }
   .sv-toggle[disabled] { opacity: 0.55; cursor: not-allowed; }
+  .sv-toggle.is-invalid { border-color: var(--sg-danger, #dc2626); }
   .sv-toggle:focus-visible { outline: 2px solid var(--sg-focus-ring, var(--_accent)); outline-offset: 2px; }
 </style>

package/src/SvTooltip.svelte

@@ -0,0 +1,113 @@
+<script lang="ts">
+  /**
+   * SvTooltip - a small hover/focus tooltip anchored to its child, portalled to
+   * <body> so it is never clipped. Shows after a short delay, hides on leave /
+   * blur / Escape, and is wired via `aria-describedby` (role="tooltip"). Respects
+   * keyboard users (opens on focus).
+   *
+   * ```svelte
+   * <SvTooltip text="Delete row"><button aria-label="Delete">🗑</button></SvTooltip>
+   * ```
+   */
+  import type { Snippet } from 'svelte'
+  import { portalToBody, popIn } from './popover'
+  import { nextEditorId } from './editor-contract'
+
+  type Props = {
+    text: string
+    placement?: 'top' | 'bottom'
+    /** Show delay in ms. Default 300. */
+    delay?: number
+    disabled?: boolean
+    children?: Snippet
+  }
+
+  let { text, placement = 'top', delay = 300, disabled = false, children }: Props = $props()
+
+  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
+
+  function place() {
+    if (!anchorEl) return
+    const r = anchorEl.getBoundingClientRect()
+    const tipH = tipEl?.offsetHeight ?? 30
+    const tipW = tipEl?.offsetWidth ?? 0
+    const top = placement === 'top' ? r.top - tipH - 8 : r.bottom + 8
+    let left = r.left + r.width / 2 - tipW / 2
+    left = Math.max(4, Math.min(left, window.innerWidth - tipW - 4))
+    // Keep the arrow under the anchor's center even when the tip is clamped.
+    const arrowX = Math.max(10, Math.min(tipW - 10, r.left + r.width / 2 - left))
+    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 }
+
+  $effect(() => {
+    if (!open) return
+    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)
+    }
+  })
+</script>
+
+<!-- svelte-ignore a11y_no_static_element_interactions -->
+<span
+  bind:this={anchorEl}
+  class="sv-tip__anchor"
+  aria-describedby={open ? tid : undefined}
+  onpointerenter={show}
+  onpointerleave={hide}
+  onfocusin={show}
+  onfocusout={hide}
+>
+  {@render children?.()}
+</span>
+
+{#if open}
+  <div
+    bind:this={tipEl}
+    id={tid}
+    class="sv-tip"
+    role="tooltip"
+    use:portalToBody
+    use:popIn={{ up: placement === 'top', duration: 110, scale: 0.9 }}
+    class:sv-tip--bottom={placement === 'bottom'}
+    style:position="fixed"
+    style:top={`${pos.top}px`}
+    style:left={`${pos.left}px`}
+    style:--tip-arrow-x={`${pos.arrowX}px`}
+  >{text}<span class="sv-tip__arrow" aria-hidden="true"></span></div>
+{/if}
+
+<style>
+  .sv-tip__anchor { display: inline-flex; }
+  :global(.sv-tip) {
+    z-index: 2147483647; pointer-events: none; position: relative;
+    max-width: 240px; padding: 5px 9px; font-size: 12px; line-height: 1.4; font-weight: 500;
+    background: var(--sg-fg, #0f172a); color: var(--sg-bg, #fff);
+    border-radius: 6px; box-shadow: 0 6px 20px -6px rgba(15, 23, 42, 0.5); white-space: normal;
+  }
+  :global(.sv-tip__arrow) {
+    position: absolute; inset-inline-start: var(--tip-arrow-x, 12px); width: 8px; height: 8px;
+    background: var(--sg-fg, #0f172a); transform: translateX(-50%) rotate(45deg);
+  }
+  :global(.sv-tip:not(.sv-tip--bottom) .sv-tip__arrow) { bottom: -3px; }
+  :global(.sv-tip--bottom .sv-tip__arrow) { top: -3px; }
+</style>