@svgrid/grid 1.2.33 → 2.0.0

package/src/SvColorInput.svelte

@@ -8,20 +8,24 @@
    * normalization, palette, draft field and open/close state come from the core;
    * the portal + anchored measurement stay here (render concerns).
    */
-  import { anchoredRect, portalToBody, type AnchoredRect } from './popover'
+  import { anchoredRect, portalToBody, popIn, type AnchoredRect } from './popover'
+  import { createDismissableLayer } from './a11y/dismissable'
+  import SvField from './SvField.svelte'
+  import { nextEditorId, resolveMessages, type SvEditorProps } from './editor-contract'
   import { createColorInput } from './createColorInput.svelte'
 
-  type Props = {
+  /** User-facing strings for the color popover (localizable via `messages`). */
+  type ColorMessages = { dialog: string; picker: string; hex: string }
+  const DEFAULT_MESSAGES: ColorMessages = { dialog: 'Choose color', picker: 'Color picker', hex: 'Hex value' }
+
+  type Props = SvEditorProps & {
     value?: string
     onChange?: (hex: string) => void
-    disabled?: boolean
-    readonly?: boolean
     /** Preset swatches. */
     palette?: string[]
-    name?: string
-    size?: 'sm' | 'md' | 'lg'
-    ariaLabel?: string
     autoOpen?: boolean
+    /** Override the built-in popover strings. */
+    messages?: Partial<ColorMessages>
   }
 
   let {
@@ -33,15 +37,32 @@
     name,
     size = 'md',
     ariaLabel,
+    invalid = false,
+    required = false,
+    error,
+    label,
+    hint,
+    dir,
+    id,
     autoOpen = false,
+    messages,
   }: Props = $props()
 
+  const autoId = nextEditorId('sv-color')
+  const uid = $derived(id ?? autoId)
+  const M = $derived(resolveMessages(DEFAULT_MESSAGES, messages))
+
   const col = createColorInput({
     value: () => value,
     onChange: (hex) => onChange?.(hex),
     disabled: () => disabled,
     readonly: () => readonly,
     palette: () => palette as string[],
+    id: () => uid,
+    invalid: () => invalid,
+    required: () => required,
+    error: () => error,
+    hint: () => hint,
     ariaLabel: () => ariaLabel,
   })
 
@@ -60,16 +81,16 @@
     const reposition = () => updatePos()
     window.addEventListener('scroll', reposition, true)
     window.addEventListener('resize', reposition)
-    const onDown = (e: PointerEvent) => {
-      const t = e.target as Node | null
-      if (t && (triggerEl?.contains(t) || panelEl?.contains(t))) return
-      col.popover.close()
-    }
-    document.addEventListener('pointerdown', onDown, true)
+    const layer = createDismissableLayer({
+      element: () => [triggerEl, panelEl],
+      onDismiss: () => col.popover.close(),
+      closeOnEscape: false,
+    })
+    layer.activate()
     return () => {
       window.removeEventListener('scroll', reposition, true)
       window.removeEventListener('resize', reposition)
-      document.removeEventListener('pointerdown', onDown, true)
+      layer.release()
     }
   })
 
@@ -79,36 +100,40 @@
   }
 </script>
 
-<button
-  bind:this={triggerEl}
-  class="sv-color sv-color--{size}"
-  class:is-disabled={disabled}
-  {...col.swatchProps()}
-  use:focusOpen
->
-  <span class="sv-color__swatch" style:background={col.normalized}></span>
-  <span class="sv-color__hex">{col.normalized}</span>
-</button>
+<SvField id={uid} {label} {hint} {error} {required} {dir}>
+  <button
+    bind:this={triggerEl}
+    class="sv-color sv-color--{size}"
+    class:is-disabled={disabled}
+    class:is-invalid={invalid}
+    {...col.swatchProps()}
+    use:focusOpen
+  >
+    <span class="sv-color__swatch" style:background={col.normalized}></span>
+    <span class="sv-color__hex">{col.normalized}</span>
+  </button>
+</SvField>
 
 {#if col.popover.open}
   <div
     class="sv-color__panel"
     bind:this={panelEl}
     use:portalToBody
+    use:popIn={{ up: panelRect.openUpward }}
     style:position="fixed"
     style:top={`${panelRect.top}px`}
     style:left={`${panelRect.left}px`}
     role="dialog"
-    aria-label="Choose color"
+    aria-label={M.dialog}
   >
     <div class="sv-color__top">
-      <input class="sv-color__native" type="color" value={col.normalized} oninput={(e) => col.pick((e.currentTarget as HTMLInputElement).value)} aria-label="Color picker" />
+      <input class="sv-color__native" type="color" value={col.normalized} oninput={(e) => col.pick((e.currentTarget as HTMLInputElement).value)} aria-label={M.picker} />
       <input
         class="sv-color__field"
         type="text"
         bind:value={col.hexDraft}
         spellcheck="false"
-        aria-label="Hex value"
+        aria-label={M.hex}
         onblur={col.commitHex}
         onkeydown={(e) => { if (e.key === 'Enter') col.commitHex() }}
       />
@@ -139,6 +164,8 @@
   .sv-color--md { height: 34px; font-size: 13px; }
   .sv-color--lg { height: 40px; font-size: 15px; }
   .sv-color.is-disabled { opacity: 0.6; cursor: not-allowed; }
+  .sv-color.is-invalid { border-color: var(--sg-danger, #dc2626); }
+  .sv-color.is-invalid:focus-within { box-shadow: 0 0 0 2px color-mix(in srgb, var(--sg-danger, #dc2626) 22%, transparent); }
   .sv-color:focus-visible { outline: 2px solid var(--sg-focus-ring, var(--_accent)); outline-offset: 2px; }
   .sv-color__swatch { width: 18px; height: 18px; border-radius: 4px; border: 1px solid rgba(0,0,0,0.15); flex: none; }
   .sv-color__hex { font-variant-numeric: tabular-nums; text-transform: lowercase; }

package/src/SvComboBox.svelte

@@ -7,37 +7,106 @@
    * This is one styled renderer over the headless `createCombobox` core (state +
    * keyboard + ARIA); only portal/measure/scroll render concerns live here.
    */
-  import { anchoredRect, portalToBody, type AnchoredRect } from './popover'
-  import { type ListOption } from './list-option'
+  import { anchoredRect, portalToBody, popIn, type AnchoredRect } from './popover'
+  import { createDismissableLayer } from './a11y/dismissable'
+  import { groupOptions, type ListOption } from './list-option'
+  import SvField from './SvField.svelte'
+  import { nextEditorId, resolveMessages, type SvEditorProps } from './editor-contract'
   import { createCombobox } from './createCombobox.svelte'
 
-  type Props = {
-    options: ReadonlyArray<ListOption>
+  /** User-facing strings (localizable via `messages`). */
+  type ComboMessages = { noResults: string; loading: string; typeMore: string }
+  const DEFAULT_MESSAGES: ComboMessages = { noResults: 'No matches', loading: 'Loading...', typeMore: 'Type to search' }
+
+  type Props = SvEditorProps & {
+    options?: ReadonlyArray<ListOption>
     value?: string | number | null
     onChange?: (value: string | number | null) => void
     placeholder?: string
-    disabled?: boolean
-    name?: string
-    size?: 'sm' | 'md' | 'lg'
-    ariaLabel?: string
     autoOpen?: boolean
+    /** Load options from a server as the user types (debounced). Disables local
+     *  filtering; the returned list is shown as-is. */
+    loadOptions?: (query: string) => Promise<ListOption[]>
+    /** Min chars before a remote search fires. Default 1. */
+    minLength?: number
+    /** Debounce (ms) before a remote search fires. Default 250. */
+    debounce?: number
+    /** Override the built-in strings (empty-state / loading text). */
+    messages?: Partial<ComboMessages>
   }
 
-  let { options, value = null, onChange, placeholder = 'Select…', disabled = false, name, size = 'md', ariaLabel, autoOpen = false }: Props = $props()
+  let {
+    options = [],
+    value = null,
+    onChange,
+    placeholder = 'Select…',
+    disabled = false,
+    name,
+    size = 'md',
+    ariaLabel,
+    invalid = false,
+    required = false,
+    error,
+    label,
+    hint,
+    dir,
+    id,
+    autoOpen = false,
+    loadOptions,
+    minLength = 1,
+    debounce = 250,
+    messages,
+  }: Props = $props()
+
+  const autoId = nextEditorId('sv-combo')
+  const uid = $derived(id ?? autoId)
+  const M = $derived(resolveMessages(DEFAULT_MESSAGES, messages))
 
   let inputEl = $state<HTMLInputElement | null>(null)
   let fieldEl = $state<HTMLDivElement | null>(null)
   let panelEl = $state<HTMLDivElement | null>(null)
   let rect = $state<AnchoredRect>({ top: 0, left: 0, width: 0, openUpward: false })
 
+  // Remote data source: fetch options as the query changes (debounced).
+  let remoteOptions = $state<ListOption[]>([])
+  let loading = $state(false)
+  let searched = $state(false)
+  let debTimer: ReturnType<typeof setTimeout> | undefined
+  let reqSeq = 0
+  const effectiveOptions = $derived(loadOptions ? remoteOptions : options)
+
   const combo = createCombobox({
-    options: () => options,
+    options: () => effectiveOptions,
     value: () => value,
     onChange: (v) => onChange?.(v),
     disabled: () => disabled,
     ariaLabel: () => ariaLabel,
+    localFilter: () => !loadOptions,
     focusInput: () => inputEl?.focus(),
     blurInput: () => inputEl?.blur(),
+    id: () => uid,
+    invalid: () => invalid,
+    required: () => required,
+    error: () => error,
+    hint: () => hint,
+  })
+
+  // Debounced remote search driven by the combobox query while editing.
+  $effect(() => {
+    if (!loadOptions) return
+    const q = combo.editing ? combo.query : ''
+    if (debTimer) clearTimeout(debTimer)
+    if (q.trim().length < minLength) { remoteOptions = []; loading = false; searched = false; return }
+    loading = true
+    const seq = ++reqSeq
+    debTimer = setTimeout(async () => {
+      try {
+        const res = await loadOptions!(q.trim())
+        if (seq === reqSeq) { remoteOptions = res; searched = true }
+      } finally {
+        if (seq === reqSeq) loading = false
+      }
+    }, debounce)
   })
 
   function updatePos() {
@@ -51,9 +120,9 @@
     updatePos()
     const rp = () => updatePos()
     window.addEventListener('scroll', rp, true); window.addEventListener('resize', rp)
-    const od = (e: PointerEvent) => { const t = e.target as Node | null; if (t && (fieldEl?.contains(t) || panelEl?.contains(t))) return; combo.close() }
-    document.addEventListener('pointerdown', od, true)
-    return () => { window.removeEventListener('scroll', rp, true); window.removeEventListener('resize', rp); document.removeEventListener('pointerdown', od, true) }
+    const layer = createDismissableLayer({ element: () => [fieldEl, panelEl], onDismiss: () => combo.close(), closeOnEscape: false })
+    layer.activate()
+    return () => { window.removeEventListener('scroll', rp, true); window.removeEventListener('resize', rp); layer.release() }
   })
   // Keep the active option scrolled into view (render concern).
   $effect(() => {
@@ -64,28 +133,39 @@
   function focusOpen(node: HTMLInputElement) { if (autoOpen) { node.focus() } }
 </script>
 
-<div bind:this={fieldEl} class="sv-combo sv-combo--{size}" class:is-open={combo.open} class:is-disabled={disabled}>
-  <input
-    bind:this={inputEl}
-    class="sv-combo__input"
-    type="text"
-    {placeholder}
-    {...combo.inputProps()}
-    use:focusOpen
-  />
-  <button class="sv-combo__chev" {...combo.triggerProps()}>
-    <svg viewBox="0 0 24 24" width="15" height="15" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><path d="m6 9 6 6 6-6" /></svg>
-  </button>
-</div>
+<SvField id={uid} {label} {hint} {error} {required} {dir}>
+  <div bind:this={fieldEl} class="sv-combo sv-combo--{size}" class:is-open={combo.open} class:is-disabled={disabled} class:is-invalid={invalid}>
+    <input
+      bind:this={inputEl}
+      class="sv-combo__input"
+      type="text"
+      {placeholder}
+      {...combo.inputProps()}
+      use:focusOpen
+    />
+    <button class="sv-combo__chev" {...combo.triggerProps()}>
+      <svg viewBox="0 0 24 24" width="15" height="15" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><path d="m6 9 6 6 6-6" /></svg>
+    </button>
+  </div>
+</SvField>
 
 {#if combo.open}
-  <div bind:this={panelEl} class="sv-ddl__panel" use:portalToBody style:position="fixed" style:top={`${rect.top}px`} style:left={`${rect.left}px`} style:min-width={`${rect.width}px`} {...combo.listboxProps()}>
-    {#each combo.filtered as opt, i (opt.value)}
-      <!-- svelte-ignore a11y_click_events_have_key_events a11y_interactive_supports_focus -->
-      <div class="sv-ddl__opt" class:is-active={combo.isActive(i)} class:is-selected={combo.isSelected(opt)} class:is-disabled={opt.disabled} {...combo.optionProps(i)}>{opt.label}</div>
+  <div bind:this={panelEl} class="sv-ddl__panel" use:portalToBody use:popIn={{ up: rect.openUpward }} style:position="fixed" style:top={`${rect.top}px`} style:left={`${rect.left}px`} style:min-width={`${rect.width}px`} {...combo.listboxProps()}>
+    {#if loading}
+      <div class="sv-ddl__empty sv-ddl__loading"><svg class="sv-ddl__spin" viewBox="0 0 24 24" width="14" height="14" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round"><path d="M21 12a9 9 0 1 1-6.2-8.6" /></svg>{M.loading}</div>
+    {:else if loadOptions && !searched && combo.query.trim().length < minLength}
+      <div class="sv-ddl__empty">{M.typeMore}</div>
+    {:else if combo.filtered.length}
+      {#each groupOptions(combo.filtered) as g (g.group ?? ' ')}
+        {#if g.group != null}<div class="sv-ddl__group-label" aria-hidden="true">{g.group}</div>{/if}
+        {#each g.options as opt (opt.value)}
+          <!-- svelte-ignore a11y_click_events_have_key_events a11y_interactive_supports_focus -->
+          <div class="sv-ddl__opt" class:is-active={combo.isActive(opt.index)} class:is-selected={combo.isSelected(opt)} class:is-disabled={opt.disabled} {...combo.optionProps(opt.index)}>{opt.label}</div>
+        {/each}
+      {/each}
     {:else}
-      <div class="sv-ddl__empty">No matches</div>
-    {/each}
+      <div class="sv-ddl__empty">{M.noResults}</div>
+    {/if}
   </div>
 {/if}
 {#if name}<input type="hidden" {name} value={value ?? ''} />{/if}
@@ -101,8 +181,14 @@
   .sv-combo--md { height: 34px; font-size: 13px; }
   .sv-combo--lg { height: 40px; font-size: 15px; }
   .sv-combo.is-open, .sv-combo:focus-within { border-color: var(--_accent); box-shadow: 0 0 0 2px color-mix(in srgb, var(--_accent) 22%, transparent); }
+  .sv-combo.is-invalid { border-color: var(--sg-danger, #dc2626); }
+  .sv-combo.is-invalid.is-open, .sv-combo.is-invalid:focus-within { box-shadow: 0 0 0 2px color-mix(in srgb, var(--sg-danger, #dc2626) 22%, transparent); }
   .sv-combo.is-disabled { opacity: 0.6; }
-  .sv-combo__input { flex: 1; min-width: 0; border: 0; background: none; outline: none; color: inherit; font: inherit; padding: 0 4px 0 10px; }
+  .sv-combo__input { flex: 1; min-width: 0; border: 0; background: none; outline: none; color: inherit; font: inherit; padding-block: 0; padding-inline: 10px 4px; }
   .sv-combo__chev { display: grid; place-items: center; width: 28px; align-self: stretch; background: none; border: 0; color: var(--sg-muted, #64748b); cursor: pointer; }
   :global(.sv-ddl__empty) { padding: 8px 10px; color: var(--sg-muted, #94a3b8); font-size: 13px; }
+  :global(.sv-ddl__loading) { display: flex; align-items: center; gap: 7px; }
+  :global(.sv-ddl__spin) { animation: sv-combo-spin 0.7s linear infinite; }
+  @keyframes sv-combo-spin { to { transform: rotate(360deg); } }
+  @media (prefers-reduced-motion: reduce) { :global(.sv-ddl__spin) { animation: none; } }
 </style>

package/src/SvCommand.svelte

@@ -0,0 +1,197 @@
+<script lang="ts" module>
+  export type { CommandItem } from './ui-app.types'
+</script>
+
+<script lang="ts">
+  /**
+   * SvCommand - a ⌘K command palette: a fuzzy-searchable list of actions in a
+   * centered, focus-trapped dialog. Built on the shared primitives (portal +
+   * focus trap + scroll lock + dismissable layer) and the pure `fuzzyScore`
+   * matcher. Optionally binds a global hotkey to toggle itself. Emits WAI-ARIA
+   * combobox markup (activedescendant).
+   *
+   * ```svelte
+   * <SvCommand commands={cmds} onRun={(c) => run(c)} />  // Cmd/Ctrl+K opens it
+   * ```
+   */
+  import type { CommandItem } from './ui-app.types'
+  import { portalToBody, popIn } from './popover'
+  import { createFocusTrap } from './a11y/focus-trap'
+  import { lockScroll } from './a11y/scroll-lock'
+  import { createDismissableLayer } from './a11y/dismissable'
+  import { fuzzyScore } from './fuzzy'
+
+  type Props = {
+    open?: boolean
+    onClose?: () => void
+    commands: ReadonlyArray<CommandItem>
+    onRun?: (cmd: CommandItem) => void
+    placeholder?: string
+    emptyText?: string
+    /** Global toggle hotkey (Cmd/Ctrl + key). `false` disables it. Default 'mod+k'. */
+    hotkey?: 'mod+k' | 'mod+p' | false
+  }
+
+  let {
+    open = $bindable(false),
+    onClose,
+    commands,
+    onRun,
+    placeholder = 'Type a command or search…',
+    emptyText = 'No results',
+    hotkey = 'mod+k',
+  }: Props = $props()
+
+  let query = $state('')
+  let active = $state(0)
+  let panelEl = $state<HTMLDivElement | null>(null)
+  let inputEl = $state<HTMLInputElement | null>(null)
+
+  const results = $derived.by(() => {
+    const q = query.trim()
+    const list = commands.filter((c) => !c.disabled)
+    if (!q) return list
+    return list
+      .map((c) => ({ c, s: fuzzyScore(`${c.label} ${c.keywords ?? ''} ${c.group ?? ''}`, q) }))
+      .filter((x) => x.s !== null)
+      .sort((a, b) => (b.s as number) - (a.s as number))
+      .map((x) => x.c)
+  })
+
+  function close() { open = false; onClose?.() }
+  function run(cmd: CommandItem | undefined) {
+    if (!cmd || cmd.disabled) return
+    close()
+    onRun?.(cmd)
+    cmd.onRun?.()
+  }
+  function move(delta: number) {
+    const n = results.length
+    if (!n) return
+    active = (active + delta + n) % n
+    queueMicrotask(() =>
+      panelEl?.querySelector(`[data-idx="${active}"]`)?.scrollIntoView({ block: 'nearest' }),
+    )
+  }
+  function onKeydown(e: KeyboardEvent) {
+    if (e.key === 'ArrowDown') { e.preventDefault(); move(1) }
+    else if (e.key === 'ArrowUp') { e.preventDefault(); move(-1) }
+    else if (e.key === 'Enter') { e.preventDefault(); run(results[active]) }
+    // Escape + outside-click are owned by the dismissable layer.
+  }
+
+  // Reset active whenever the query changes.
+  $effect(() => { void query; active = 0 })
+
+  // Focus + scroll lock + Escape/outside dismissal while open.
+  $effect(() => {
+    if (!open || !panelEl) return
+    query = ''
+    active = 0
+    const trap = createFocusTrap(panelEl, { initialFocus: () => inputEl })
+    trap.activate()
+    const unlock = lockScroll()
+    const layer = createDismissableLayer({ element: () => panelEl, onDismiss: () => close() })
+    layer.activate()
+    return () => { layer.release(); unlock(); trap.release() }
+  })
+
+  // Global toggle hotkey.
+  $effect(() => {
+    if (!hotkey) return
+    const key = hotkey === 'mod+p' ? 'p' : 'k'
+    const onKey = (e: KeyboardEvent) => {
+      if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === key) {
+        e.preventDefault()
+        open = !open
+      }
+    }
+    window.addEventListener('keydown', onKey)
+    return () => window.removeEventListener('keydown', onKey)
+  })
+</script>
+
+{#if open}
+  <div class="sv-cmd__backdrop" use:portalToBody>
+    <div
+      bind:this={panelEl}
+      class="sv-cmd"
+      use:popIn={{}}
+      role="dialog"
+      aria-modal="true"
+      aria-label="Command palette"
+      tabindex="-1"
+      onkeydown={onKeydown}
+    >
+      <div class="sv-cmd__search">
+        <span class="sv-cmd__searchicon" aria-hidden="true">⌕</span>
+        <input
+          bind:this={inputEl}
+          class="sv-cmd__input"
+          type="text"
+          role="combobox"
+          aria-expanded="true"
+          aria-controls="sv-cmd-list"
+          aria-activedescendant={results[active] ? `sv-cmd-opt-${active}` : undefined}
+          {placeholder}
+          value={query}
+          oninput={(e) => (query = e.currentTarget.value)}
+        />
+      </div>
+      <ul class="sv-cmd__list" id="sv-cmd-list" role="listbox" aria-label="Commands">
+        {#each results as c, i (c.id)}
+          {#if !query.trim() && c.group && c.group !== results[i - 1]?.group}
+            <li class="sv-cmd__group" role="presentation">{c.group}</li>
+          {/if}
+          <li
+            id={`sv-cmd-opt-${i}`}
+            data-idx={i}
+            class="sv-cmd__opt"
+            class:is-active={i === active}
+            role="option"
+            aria-selected={i === active}
+            onpointermove={() => (active = i)}
+            onclick={() => run(c)}
+          >
+            {#if c.icon}<span class="sv-cmd__icon" aria-hidden="true">{c.icon}</span>{/if}
+            <span class="sv-cmd__label">{c.label}</span>
+            {#if c.hint}<span class="sv-cmd__hint">{c.hint}</span>{/if}
+            {#if c.shortcut}<span class="sv-cmd__kbd">{c.shortcut}</span>{/if}
+          </li>
+        {:else}
+          <li class="sv-cmd__empty" aria-disabled="true">{emptyText}</li>
+        {/each}
+      </ul>
+    </div>
+  </div>
+{/if}
+
+<style>
+  :global(.sv-cmd__backdrop) {
+    position: fixed; inset: 0; z-index: 2147483000; display: flex; justify-content: center;
+    align-items: flex-start; padding: 12vh 16px 16px;
+    background: rgba(15, 23, 42, 0.42); backdrop-filter: blur(2px);
+    animation: sv-cmd-fade 0.14s ease both;
+  }
+  @keyframes sv-cmd-fade { from { opacity: 0 } to { opacity: 1 } }
+  :global(.sv-cmd) {
+    width: min(560px, 100%); max-height: 62vh; display: flex; flex-direction: column; overflow: hidden;
+    background: var(--sg-bg, #fff); color: var(--sg-fg, #0f172a);
+    border: 1px solid var(--sg-border, #e2e8f0); border-radius: 14px;
+    box-shadow: 0 24px 64px -16px rgba(15, 23, 42, 0.5);
+  }
+  :global(.sv-cmd__search) { display: flex; align-items: center; gap: 8px; padding: 12px 14px; border-bottom: 1px solid var(--sg-border, #e2e8f0); }
+  :global(.sv-cmd__searchicon) { color: var(--sg-muted, #64748b); font-size: 18px; }
+  :global(.sv-cmd__input) { flex: 1; min-width: 0; border: 0; background: none; outline: none; font: inherit; font-size: 15px; color: var(--sg-fg, #0f172a); }
+  :global(.sv-cmd__list) { list-style: none; margin: 0; padding: 6px; overflow: auto; }
+  :global(.sv-cmd__group) { padding: 8px 10px 4px; font-size: 11px; font-weight: 650; text-transform: uppercase; letter-spacing: 0.03em; color: var(--sg-muted, #94a3b8); }
+  :global(.sv-cmd__opt) { display: flex; align-items: center; gap: 10px; padding: 9px 10px; border-radius: 8px; cursor: pointer; font-size: 13.5px; }
+  :global(.sv-cmd__opt.is-active) { background: var(--sg-accent, #2563eb); color: var(--sg-on-accent, #fff); }
+  :global(.sv-cmd__icon) { flex: none; width: 20px; text-align: center; }
+  :global(.sv-cmd__label) { flex: none; }
+  :global(.sv-cmd__hint) { flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; color: var(--sg-muted, #94a3b8); font-size: 12.5px; }
+  :global(.sv-cmd__opt.is-active .sv-cmd__hint) { color: color-mix(in srgb, var(--sg-on-accent, #fff) 80%, transparent); }
+  :global(.sv-cmd__kbd) { flex: none; margin-inline-start: auto; font-size: 11px; padding: 1px 6px; border-radius: 5px; background: color-mix(in srgb, var(--sg-fg, #0f172a) 8%, transparent); color: var(--sg-muted, #64748b); }
+  :global(.sv-cmd__opt.is-active .sv-cmd__kbd) { background: color-mix(in srgb, var(--sg-on-accent, #fff) 22%, transparent); color: var(--sg-on-accent, #fff); }
+  :global(.sv-cmd__empty) { padding: 22px; text-align: center; color: var(--sg-muted, #94a3b8); font-size: 13px; }
+</style>

package/src/SvContextMenu.svelte

@@ -0,0 +1,96 @@
+<script lang="ts" module>
+  export type { MenuItem } from './SvMenuList.svelte'
+</script>
+
+<script lang="ts">
+  /**
+   * SvContextMenu - wraps a region and opens a menu at the pointer on right-click
+   * (or long-press). Reuses SvMenuList (submenus, keyboard, icons, shortcuts),
+   * portals to <body>, and closes via the shared dismissable layer stack.
+   * Parity: Smart context-menu.
+   *
+   * ```svelte
+   * <SvContextMenu items={items} onSelect={(i) => run(i)}>
+   *   <div class="drop-zone">Right-click me</div>
+   * </SvContextMenu>
+   * ```
+   */
+  import type { Snippet } from 'svelte'
+  import { portalToBody, popIn } from './popover'
+  import { createDismissableLayer } from './a11y/dismissable'
+  import SvMenuList, { type MenuItem } from './SvMenuList.svelte'
+
+  type Props = {
+    items: ReadonlyArray<MenuItem>
+    onSelect?: (item: MenuItem) => void
+    disabled?: boolean
+    ariaLabel?: string
+    children?: Snippet
+  }
+
+  let { items, onSelect, disabled = false, ariaLabel, children }: Props = $props()
+
+  let open = $state(false)
+  let pos = $state({ x: 0, y: 0 })
+  let panelEl = $state<HTMLDivElement | null>(null)
+
+  const MENU_W = 200
+  function openAt(clientX: number, clientY: number) {
+    // Clamp so the menu stays on-screen (estimate height from item count).
+    const estH = Math.min(items.length, 12) * 34 + 8
+    const x = Math.min(clientX, window.innerWidth - MENU_W - 6)
+    const y = Math.min(clientY, window.innerHeight - estH - 6)
+    pos = { x: Math.max(6, x), y: Math.max(6, y) }
+    open = true
+  }
+
+  function onContextMenu(e: MouseEvent) {
+    if (disabled) return
+    e.preventDefault()
+    openAt(e.clientX, e.clientY)
+  }
+
+  $effect(() => {
+    if (!open) return
+    queueMicrotask(() => panelEl?.querySelector<HTMLElement>('[role="menuitem"]:not([disabled])')?.focus())
+    const layer = createDismissableLayer({
+      element: () => panelEl,
+      onDismiss: () => (open = false),
+    })
+    layer.activate()
+    // Reposition-close on scroll (a moved anchor would leave the menu stranded).
+    const onScroll = () => (open = false)
+    window.addEventListener('scroll', onScroll, true)
+    return () => { layer.release(); window.removeEventListener('scroll', onScroll, true) }
+  })
+</script>
+
+<!-- svelte-ignore a11y_no_static_element_interactions -->
+<div class="sv-ctx__zone" oncontextmenu={onContextMenu}>
+  {@render children?.()}
+</div>
+
+{#if open}
+  <div
+    bind:this={panelEl}
+    class="sv-ctx"
+    use:portalToBody
+    use:popIn={{}}
+    style:position="fixed"
+    style:top={`${pos.y}px`}
+    style:left={`${pos.x}px`}
+    aria-label={ariaLabel}
+  >
+    <SvMenuList {items} onclose={() => (open = false)} onselect={(i) => onSelect?.(i)} />
+  </div>
+{/if}
+
+<style>
+  .sv-ctx__zone { display: contents; }
+  :global(.sv-ctx) {
+    z-index: 2147483646; min-width: 200px;
+    background: var(--sg-bg, #fff); color: var(--sg-fg, #0f172a);
+    border: 1px solid var(--sg-border, #e2e8f0); border-radius: 10px;
+    box-shadow: 0 16px 48px -12px rgba(15, 23, 42, 0.35); font-size: 13px;
+  }
+</style>