@svgrid/grid 1.2.34 → 2.0.1

package/src/SvListBox.svelte

@@ -2,26 +2,55 @@
   /**
    * SvListBox - an inline single/multi-select list (WAI-ARIA listbox) with
    * roving highlight + full keyboard. Parity: Smart `smart-list-box`. Controlled
-   * via `value` (scalar or array) + `onChange`.
+   * via `value` (scalar or array) + `onChange`. Scales to huge option sets with
+   * `virtual` (fixed-row windowing), and each row can be an `itemTemplate`.
    */
-  import type { ListOption } from './list-option'
+  import { flushSync, type Snippet } from 'svelte'
+  import { groupOptions, hasGroups, type ListOption } from './list-option'
+  import { virtualRange, scrollToIndex } from './virtual'
   import { createListbox } from './createListbox.svelte'
+  import SvField from './SvField.svelte'
+  import { nextEditorId, type SvEditorProps } from './editor-contract'
 
-  type Props = {
+  type Props = SvEditorProps & {
     options: ReadonlyArray<ListOption>
     value?: string | number | Array<string | number> | null
     onChange?: (value: any) => void
     multiple?: boolean
-    disabled?: boolean
     /** Visible height in rows before scrolling. */
     rows?: number
-    ariaLabel?: string
-    /** Form field name; emits a hidden input per selected value so the listbox
-     *  posts in a native <form> (multiple selection -> repeated name). */
-    name?: string
+    /** Window the list (render only visible rows) for large option sets. */
+    virtual?: boolean
+    /** Fixed row height in px (must match the CSS row height). Default 32. */
+    rowHeight?: number
+    /** Custom per-option content. Receives the option. */
+    itemTemplate?: Snippet<[ListOption]>
   }
 
-  let { options, value = null, onChange, multiple = false, disabled = false, rows = 7, ariaLabel, name }: Props = $props()
+  let {
+    options,
+    value = null,
+    onChange,
+    multiple = false,
+    disabled = false,
+    rows = 7,
+    virtual = false,
+    rowHeight = 32,
+    itemTemplate,
+    ariaLabel,
+    name,
+    invalid = false,
+    required = false,
+    error,
+    label,
+    hint,
+    dir,
+    id,
+  }: Props = $props()
+
+  // Stable id anchors the label/hint/error wiring even when no `id` is passed.
+  const autoId = nextEditorId('sv-lb')
+  const uid = $derived(id ?? autoId)
 
   // The styled listbox is just a renderer over the headless core.
   const lb = createListbox({
@@ -31,40 +60,85 @@
     multiple: () => multiple,
     disabled: () => disabled,
     ariaLabel: () => ariaLabel,
+    id: () => uid,
+    invalid: () => invalid,
+    required: () => required,
+    error: () => error,
+    hint: () => hint,
   })
   const isSel = (o: ListOption) => lb.isSelected(o.value)
 
-  let listEl: HTMLUListElement | null = null
-  // Scroll-into-view is a render concern, so it lives here (not in the core).
+  // Virtualization only applies to a flat (ungrouped) list.
+  const useVirtual = $derived(virtual && !hasGroups(options))
+  let listEl = $state<HTMLUListElement | null>(null)
+  let scrollTop = $state(0)
+  let viewportH = $state(0)
+  const vr = $derived(
+    virtualRange({ scrollTop, viewportHeight: viewportH, rowHeight, count: options.length, overscan: 10 }),
+  )
+  const windowed = $derived(
+    useVirtual ? options.slice(vr.start, vr.end).map((o, i) => ({ ...o, index: vr.start + i })) : [],
+  )
+
+  // Keep the active option in view. Virtual mode drives scrollTop directly (the
+  // active row may not be in the DOM); otherwise use scrollIntoView.
   $effect(() => {
     const i = lb.activeIndex
-    queueMicrotask(() => listEl?.querySelector<HTMLElement>(`[data-idx="${i}"]`)?.scrollIntoView({ block: 'nearest' }))
+    if (useVirtual) {
+      if (!listEl) return
+      const next = scrollToIndex(i, listEl.scrollTop, listEl.clientHeight, rowHeight)
+      if (next !== listEl.scrollTop) listEl.scrollTop = next
+    } else {
+      queueMicrotask(() => listEl?.querySelector<HTMLElement>(`[data-idx="${i}"]`)?.scrollIntoView({ block: 'nearest' }))
+    }
   })
 </script>
 
-<div style="display: contents">
-<ul
-  bind:this={listEl}
-  class="sv-listbox"
-  style:--sv-rows={rows}
-  {...lb.rootProps()}
->
-  {#each options as opt, i (opt.value)}
-    <!-- svelte-ignore a11y_click_events_have_key_events a11y_interactive_supports_focus -->
-    <li
-      class="sv-listbox__opt"
-      class:is-selected={isSel(opt)}
-      class:is-active={lb.isActive(i)}
-      class:is-disabled={opt.disabled}
-      {...lb.optionProps(i)}
-    >
-      {#if multiple}<span class="sv-listbox__check" aria-hidden="true">{isSel(opt) ? '✓' : ''}</span>{/if}
-      <span class="sv-listbox__label">{opt.label}</span>
-    </li>
-  {/each}
-</ul>
-{#if name}{#each lb.selectedValues as v (v)}<input type="hidden" {name} value={v} />{/each}{/if}
-</div>
+<SvField id={uid} {label} {hint} {error} {required} {dir}>
+  <ul
+    bind:this={listEl}
+    class="sv-listbox"
+    class:is-invalid={invalid}
+    class:is-virtual={useVirtual}
+    style:--sv-rows={rows}
+    onscroll={(e) => { scrollTop = e.currentTarget.scrollTop; if (useVirtual) flushSync() }}
+    bind:clientHeight={viewportH}
+    {...lb.rootProps()}
+  >
+    {#if useVirtual}
+      <!-- Fixed-height sizer establishes the scroll range; rows are absolutely
+           positioned by transform so scrolling never reflows (no flash). -->
+      <li class="sv-listbox__sizer" aria-hidden="true" style:height={`${vr.totalHeight}px`}></li>
+      {#each windowed as opt (opt.value)}
+        {@render optionLi(opt, opt.index)}
+      {/each}
+    {:else}
+      {#each groupOptions(options) as g (g.group ?? ' ')}
+        {#if g.group != null}<li class="sv-listbox__group" role="presentation">{g.group}</li>{/if}
+        {#each g.options as opt (opt.value)}
+          {@render optionLi(opt, opt.index)}
+        {/each}
+      {/each}
+    {/if}
+  </ul>
+  {#if name}{#each lb.selectedValues as v (v)}<input type="hidden" {name} value={v} />{/each}{/if}
+</SvField>
+
+{#snippet optionLi(opt, index)}
+  <!-- svelte-ignore a11y_click_events_have_key_events a11y_interactive_supports_focus -->
+  <li
+    class="sv-listbox__opt"
+    class:is-selected={isSel(opt)}
+    class:is-active={lb.isActive(index)}
+    class:is-disabled={opt.disabled}
+    style:height={`${rowHeight}px`}
+    style:transform={useVirtual ? `translateY(${index * rowHeight}px)` : undefined}
+    {...lb.optionProps(index)}
+  >
+    {#if multiple}<span class="sv-listbox__check" aria-hidden="true">{isSel(opt) ? '✓' : ''}</span>{/if}
+    {#if itemTemplate}{@render itemTemplate(opt)}{:else}<span class="sv-listbox__label">{opt.label}</span>{/if}
+  </li>
+{/snippet}
 
 <style>
   .sv-listbox {
@@ -76,14 +150,27 @@
     width: 220px; outline: none;
   }
   .sv-listbox:focus-visible { border-color: var(--_accent); box-shadow: 0 0 0 2px color-mix(in srgb, var(--_accent) 22%, transparent); }
+  .sv-listbox.is-invalid { border-color: var(--sg-danger, #dc2626); }
+  .sv-listbox.is-invalid:focus-visible { box-shadow: 0 0 0 2px color-mix(in srgb, var(--sg-danger, #dc2626) 22%, transparent); }
+  /* Pre-promote the scrolling-contents layer at mount so the FIRST scroll
+     doesn't trigger a one-time layer promotion + repaint (the initial flash). */
+  .sv-listbox.is-virtual { position: relative; will-change: scroll-position; }
+  .sv-listbox__sizer { padding: 0; margin: 0; pointer-events: none; }
+  .sv-listbox.is-virtual .sv-listbox__opt {
+    position: absolute; inset-inline: 4px; top: 4px;
+  }
   .sv-listbox__opt {
-    display: flex; align-items: center; gap: 8px; height: 32px; padding: 0 10px;
+    display: flex; align-items: center; gap: 8px; box-sizing: border-box; padding: 0 10px;
     border-radius: 6px; cursor: pointer; font-size: 13px;
   }
   .sv-listbox__opt.is-active { background: var(--sg-row-hover-bg, #f1f5f9); }
   .sv-listbox__opt.is-selected { background: color-mix(in srgb, var(--_accent) 14%, transparent); color: var(--_accent); font-weight: 600; }
   .sv-listbox__opt.is-selected.is-active { background: color-mix(in srgb, var(--_accent) 22%, transparent); }
   .sv-listbox__opt.is-disabled { opacity: 0.4; cursor: not-allowed; }
+  .sv-listbox__group {
+    padding: 8px 10px 3px; font-size: 10.5px; font-weight: 700; text-transform: uppercase; letter-spacing: 0.04em;
+    color: var(--sg-muted, #94a3b8);
+  }
   .sv-listbox__check { width: 14px; text-align: center; color: var(--_accent); }
   .sv-listbox__label { flex: 1; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
 </style>

package/src/SvMaskedInput.svelte

@@ -7,20 +7,23 @@
    * The styled renderer over the headless `createMaskedInput` core; the mask
    * formatting + state live in the core, spread here via prop-getters.
    */
+  import type { Snippet } from 'svelte'
   import { unmask } from './datetime/mask'
+  import SvField from './SvField.svelte'
+  import { nextEditorId, type SvEditorProps } from './editor-contract'
   import { createMaskedInput } from './createMaskedInput.svelte'
 
-  type Props = {
+  type Props = SvEditorProps & {
     value?: string
     /** Called with (masked, raw, complete). */
     onChange?: (masked: string, raw: string, complete: boolean) => void
     mask?: string
     placeholder?: string
-    disabled?: boolean
-    readonly?: boolean
-    name?: string
-    size?: 'sm' | 'md' | 'lg'
-    ariaLabel?: string
+    /** Show a clear (x) button when there is a value. */
+    clearable?: boolean
+    /** Leading / trailing icon adornments. */
+    prefixIcon?: Snippet
+    suffixIcon?: Snippet
   }
 
   let {
@@ -33,8 +36,21 @@
     name,
     size = 'md',
     ariaLabel,
+    invalid = false,
+    required = false,
+    error,
+    label,
+    hint,
+    dir,
+    id,
+    clearable = false,
+    prefixIcon,
+    suffixIcon,
   }: Props = $props()
 
+  const autoId = nextEditorId('sv-mask')
+  const uid = $derived(id ?? autoId)
+
   const mi = createMaskedInput({
     value: () => value,
     onChange: (m, r, c) => onChange?.(m, r, c),
@@ -42,25 +58,49 @@
     placeholder: () => placeholder,
     disabled: () => disabled,
     readonly: () => readonly,
+    id: () => uid,
+    invalid: () => invalid,
+    required: () => required,
+    error: () => error,
+    hint: () => hint,
     ariaLabel: () => ariaLabel,
   })
 </script>
 
-<input class="sv-masked sv-masked--{size}" {...mi.inputProps()} />
-{#if name}<input type="hidden" {name} value={mask ? unmask(mi.masked, mask) : mi.masked} />{/if}
+<SvField id={uid} {label} {hint} {error} {required} {dir}>
+  <div class="sv-masked sv-masked--{size}" class:is-invalid={invalid} class:is-disabled={disabled}>
+    {#if prefixIcon}<span class="sv-masked__adorn">{@render prefixIcon()}</span>{/if}
+    <input class="sv-masked__input" {...mi.inputProps()} />
+    {#if clearable && mi.masked && !disabled && !readonly}
+      <button type="button" class="sv-masked__clear" aria-label="Clear" tabindex="-1" onclick={() => onChange?.('', '', false)}>
+        <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}
+    {#if suffixIcon}<span class="sv-masked__adorn">{@render suffixIcon()}</span>{/if}
+    {#if name}<input type="hidden" {name} value={mask ? unmask(mi.masked, mask) : mi.masked} />{/if}
+  </div>
+</SvField>
 
 <style>
   .sv-masked {
     --_accent: var(--sg-accent, #2563eb);
-    box-sizing: border-box; width: 200px;
+    box-sizing: border-box; width: 200px; display: inline-flex; align-items: center; gap: 6px;
     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);
-    font: inherit; padding: 0 10px; outline: none;
-    font-variant-numeric: tabular-nums; letter-spacing: 0.02em;
+    font: inherit; padding: 0 8px 0 10px;
   }
   .sv-masked--sm { height: 28px; font-size: 12px; }
   .sv-masked--md { height: 34px; font-size: 13px; }
   .sv-masked--lg { height: 40px; font-size: 15px; }
-  .sv-masked:focus { border-color: var(--_accent); box-shadow: 0 0 0 2px color-mix(in srgb, var(--_accent) 22%, transparent); }
-  .sv-masked:disabled { opacity: 0.6; }
+  .sv-masked:focus-within { border-color: var(--_accent); box-shadow: 0 0 0 2px color-mix(in srgb, var(--_accent) 22%, transparent); }
+  .sv-masked.is-invalid { border-color: var(--sg-danger, #dc2626); }
+  .sv-masked.is-invalid:focus-within { box-shadow: 0 0 0 2px color-mix(in srgb, var(--sg-danger, #dc2626) 22%, transparent); }
+  .sv-masked.is-disabled { opacity: 0.6; }
+  .sv-masked__input {
+    flex: 1; min-width: 0; border: 0; background: none; outline: none; color: inherit; font: inherit;
+    font-variant-numeric: tabular-nums; letter-spacing: 0.02em;
+  }
+  .sv-masked__adorn { display: inline-flex; flex: none; color: var(--sg-muted, #64748b); }
+  .sv-masked__clear { display: grid; place-items: center; width: 20px; flex: none; background: none; border: 0; color: var(--sg-muted, #64748b); cursor: pointer; border-radius: 4px; }
+  .sv-masked__clear:hover { color: var(--sg-danger, #dc2626); }
 </style>

package/src/SvMenu.svelte

@@ -0,0 +1,101 @@
+<script lang="ts" module>
+  export type { MenuItem } from './SvMenuList.svelte'
+</script>
+
+<script lang="ts">
+  /**
+   * SvMenu - a dropdown / context menu: a trigger opens a portalled, animated
+   * menu surface with submenus, separators, icons, shortcuts and full keyboard
+   * (arrows, Enter, Escape, ArrowRight/Left for submenus). Portals to <body> so it
+   * escapes any clipping. Parity: Smart menu / context-menu.
+   *
+   * ```svelte
+   * <SvMenu items={items} onSelect={(i) => run(i)}>
+   *   {#snippet anchor()}<button>Actions</button>{/snippet}
+   * </SvMenu>
+   * ```
+   */
+  import type { Snippet } from 'svelte'
+  import { anchoredRect, portalToBody, popIn, type AnchoredRect } from './popover'
+  import { createDismissableLayer } from './a11y/dismissable'
+  import SvMenuList, { type MenuItem } from './SvMenuList.svelte'
+
+  let {
+    items,
+    open = $bindable(false),
+    onOpenChange,
+    onSelect,
+    ariaLabel,
+    anchor,
+  }: {
+    items: ReadonlyArray<MenuItem>
+    open?: boolean
+    onOpenChange?: (open: boolean) => void
+    onSelect?: (item: MenuItem) => void
+    ariaLabel?: string
+    anchor?: Snippet
+  } = $props()
+
+  let anchorEl = $state<HTMLSpanElement | null>(null)
+  let panelEl = $state<HTMLDivElement | null>(null)
+  let rect = $state<AnchoredRect>({ top: 0, left: 0, width: 0, openUpward: false })
+
+  function setOpen(v: boolean) { if (v !== open) { open = v; onOpenChange?.(v) } }
+  function toggle() { setOpen(!open) }
+  function updatePos() {
+    if (!anchorEl) return
+    rect = anchoredRect(anchorEl.getBoundingClientRect(), { estimatedHeight: Math.min(items.length, 10) * 34 + 8, minWidth: 180 })
+  }
+
+  $effect(() => {
+    if (!open) return
+    updatePos()
+    queueMicrotask(() => panelEl?.querySelector<HTMLElement>('[role="menuitem"]:not([disabled])')?.focus())
+    const rp = () => updatePos()
+    window.addEventListener('scroll', rp, true)
+    window.addEventListener('resize', rp)
+    // Outside-click dismissal via the shared layer stack (Escape stays owned by
+    // SvMenuList's keyboard handling, so closeOnEscape is off here).
+    const layer = createDismissableLayer({
+      element: () => [anchorEl, panelEl],
+      onDismiss: () => setOpen(false),
+      closeOnEscape: false,
+    })
+    layer.activate()
+    return () => {
+      window.removeEventListener('scroll', rp, true)
+      window.removeEventListener('resize', rp)
+      layer.release()
+    }
+  })
+</script>
+
+<!-- svelte-ignore a11y_no_static_element_interactions a11y_click_events_have_key_events -->
+<span bind:this={anchorEl} class="sv-menu__anchor" onclick={toggle}>
+  {@render anchor?.()}
+</span>
+
+{#if open}
+  <div
+    bind:this={panelEl}
+    class="sv-menu"
+    use:portalToBody
+    use:popIn={{ up: rect.openUpward }}
+    style:position="fixed"
+    style:top={`${rect.top}px`}
+    style:left={`${rect.left}px`}
+    aria-label={ariaLabel}
+  >
+    <SvMenuList {items} onclose={() => setOpen(false)} onselect={(i) => onSelect?.(i)} />
+  </div>
+{/if}
+
+<style>
+  .sv-menu__anchor { display: inline-flex; }
+  :global(.sv-menu) {
+    z-index: 2147483646; min-width: 180px;
+    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>

package/src/SvMenu.test.ts

@@ -0,0 +1,73 @@
+/**
+ * Component tests for SvMenu: the trigger opens a portalled menu, items/separators
+ * render with menu semantics, choosing a leaf fires onSelect + closes, and a
+ * submenu opens on pointer-enter.
+ */
+import { describe, expect, it, afterEach } from 'vitest'
+import { mount, unmount, flushSync, createRawSnippet } from 'svelte'
+import SvMenu, { type MenuItem } from './SvMenu.svelte'
+
+const anchor = createRawSnippet(() => ({ render: () => `<button class="trigger">Actions</button>` }))
+
+function mountMenu(props: Record<string, unknown>) {
+  const target = document.createElement('div')
+  document.body.appendChild(target)
+  const app = mount(SvMenu, { target, props: { anchor, ...props } as any })
+  flushSync()
+  return { target, destroy: () => { unmount(app); target.remove() } }
+}
+const menu = () => document.querySelector<HTMLElement>('.sv-menu')
+afterEach(() => document.querySelectorAll('.sv-menu').forEach((n) => n.remove()))
+
+describe('SvMenu', () => {
+  const items: MenuItem[] = [
+    { label: 'Cut', shortcut: 'Ctrl+X', onSelect: () => {} },
+    { label: 'Copy', shortcut: 'Ctrl+C' },
+    { separator: true },
+    { label: 'Share', children: [{ label: 'Email' }, { label: 'Link' }] },
+    { label: 'Delete', disabled: true },
+  ]
+
+  it('opens on trigger click with menu/menuitem roles + a separator', () => {
+    const { target, destroy } = mountMenu({ items })
+    try {
+      expect(menu()).toBeNull()
+      target.querySelector<HTMLElement>('.trigger')!.click()
+      flushSync()
+      const m = menu()!
+      expect(m.querySelector('[role="menu"]')).not.toBeNull()
+      expect(m.querySelectorAll('[role="menuitem"]').length).toBe(4) // 4 items, separator excluded
+      expect(m.querySelector('[role="separator"]')).not.toBeNull()
+      expect(m.querySelector('[aria-disabled="true"]')).not.toBeNull()
+    } finally { destroy() }
+  })
+
+  it('choosing a leaf fires onSelect and closes', () => {
+    let chosen: MenuItem | undefined
+    const { target, destroy } = mountMenu({ items, onSelect: (i: MenuItem) => (chosen = i) })
+    try {
+      target.querySelector<HTMLElement>('.trigger')!.click()
+      flushSync()
+      const copy = [...menu()!.querySelectorAll<HTMLElement>('[role="menuitem"]')].find((b) => b.textContent?.includes('Copy'))!
+      copy.click()
+      flushSync()
+      expect(chosen?.label).toBe('Copy')
+      expect(menu()).toBeNull()
+    } finally { destroy() }
+  })
+
+  it('opens a submenu on pointer-enter of a parent item', () => {
+    const { target, destroy } = mountMenu({ items })
+    try {
+      target.querySelector<HTMLElement>('.trigger')!.click()
+      flushSync()
+      const share = [...menu()!.querySelectorAll<HTMLElement>('[role="menuitem"]')].find((b) => b.textContent?.includes('Share'))!
+      expect(share.getAttribute('aria-haspopup')).toBe('menu')
+      share.dispatchEvent(new PointerEvent('pointerenter', { bubbles: true }))
+      flushSync()
+      expect(menu()!.querySelector('.sv-menu__flyout')).not.toBeNull()
+      const sub = [...menu()!.querySelectorAll('[role="menuitem"]')].map((b) => b.textContent)
+      expect(sub.some((t) => t?.includes('Email'))).toBe(true)
+    } finally { destroy() }
+  })
+})

package/src/SvMenuList.svelte

@@ -0,0 +1,143 @@
+<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
+  }
+</script>
+
+<script lang="ts">
+  /**
+   * SvMenuList - the recursive menu surface behind SvMenu: a WAI-ARIA `menu` with
+   * roving focus, submenus (hover + ArrowRight), separators, icons and shortcuts.
+   * Rendered inside a portalled panel by SvMenu; it self-imports for submenus.
+   */
+  import Self from './SvMenuList.svelte'
+
+  let {
+    items,
+    onclose,
+    onselect,
+    submenu = false,
+  }: {
+    items: ReadonlyArray<MenuItem>
+    /** Close the WHOLE menu (a leaf was chosen or Escape at the root). */
+    onclose: () => void
+    /** Report the chosen leaf item. */
+    onselect: (item: MenuItem) => void
+    submenu?: boolean
+  } = $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]
+    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':
+        if (item?.children?.length) { e.preventDefault(); openSub = i }
+        break
+      case 'ArrowLeft':
+        if (submenu) { e.preventDefault(); onclose() } // parent listens via its own onclose wiring
+        break
+      case 'Enter':
+      case ' ': e.preventDefault(); if (item) choose(item); break
+      case 'Escape': e.preventDefault(); onclose(); break
+    }
+  }
+</script>
+
+<!-- svelte-ignore a11y_no_noninteractive_element_interactions -->
+<div bind:this={listEl} class="sv-menu__list" class:is-submenu={submenu} role="menu">
+  {#each items as item, i (i)}
+    {#if item.separator}
+      <div class="sv-menu__sep" role="separator"></div>
+    {:else}
+      <div class="sv-menu__itemwrap">
+        <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)}
+        >
+          <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}
+          <div class="sv-menu__flyout">
+            <Self items={item.children} onclose={onclose} onselect={onselect} submenu />
+          </div>
+        {/if}
+      </div>
+    {/if}
+  {/each}
+</div>
+
+<style>
+  .sv-menu__list { display: flex; flex-direction: column; min-width: 180px; padding: 4px; }
+  .sv-menu__sep { height: 1px; background: var(--sg-border, #e2e8f0); margin: 4px 6px; }
+  .sv-menu__itemwrap { position: relative; }
+  .sv-menu__item {
+    display: flex; align-items: center; gap: 9px; width: 100%; box-sizing: border-box;
+    padding: 7px 10px; background: none; border: 0; border-radius: 6px; cursor: pointer;
+    font: inherit; font-size: 13px; color: var(--sg-fg, #0f172a); text-align: start;
+    transition: background 0.1s;
+  }
+  .sv-menu__item.is-active:not([disabled]), .sv-menu__item:hover:not([disabled]) { background: var(--sg-row-hover-bg, #f1f5f9); }
+  .sv-menu__item:focus-visible { outline: 2px solid var(--sg-focus-ring, var(--sg-accent, #2563eb)); outline-offset: -2px; }
+  .sv-menu__item[disabled] { opacity: 0.45; cursor: default; }
+  .sv-menu__icon { display: inline-flex; width: 16px; flex: none; color: var(--sg-muted, #64748b); }
+  .sv-menu__icon:empty { width: 0; }
+  .sv-menu__label { flex: 1; white-space: nowrap; }
+  .sv-menu__shortcut { color: var(--sg-muted, #94a3b8); font-size: 11.5px; margin-inline-start: 12px; }
+  .sv-menu__chev { color: var(--sg-muted, #94a3b8); flex: none; }
+  .sv-menu[dir='rtl'] .sv-menu__chev, .sv-menu__list.is-submenu .sv-menu__chev { }
+  .sv-menu__flyout {
+    position: absolute; top: -5px; inset-inline-start: 100%; z-index: 1;
+    background: var(--sg-bg, #fff); border: 1px solid var(--sg-border, #e2e8f0);
+    border-radius: 10px; box-shadow: 0 16px 40px -12px rgba(15,23,42,0.32); margin-inline-start: 2px;
+  }
+</style>