@svgrid/grid 1.2.33 → 2.0.0

package/src/SvGridSelect.svelte

@@ -0,0 +1,255 @@
+<script lang="ts" module>
+  export type { GridSelectColumn } from './ui-app.types'
+</script>
+
+<script lang="ts">
+  /**
+   * SvGridSelect - a "grid in a dropdown" single-select: the panel shows the
+   * options as a compact multi-column table (header row + optional search), so
+   * you pick by more than a label. The open / position / dismiss / roving /
+   * keyboard / ARIA mechanics come from the shared `createPopoverSelect` core;
+   * this component adds the multi-column table. It does NOT embed the full
+   * SvGrid. Emits the chosen row's id. Parity: Smart multicolumn combobox.
+   */
+  import type { GridSelectColumn } from './ui-app.types'
+  import SvField from './SvField.svelte'
+  import { editorAria, nextEditorId, type SvEditorProps } from './editor-contract'
+  import { portalToBody, popIn } from './popover'
+  import { createPopoverSelect } from './createPopoverSelect.svelte'
+  import { debounce } from './debounce'
+  import { filterGridRows, type Row } from './grid-select'
+
+  type Props = Pick<
+    SvEditorProps,
+    'disabled' | 'label' | 'hint' | 'error' | 'required' | 'invalid' | 'size' | 'id' | 'name' | 'dir' | 'ariaLabel'
+  > & {
+    columns: ReadonlyArray<GridSelectColumn>
+    options: ReadonlyArray<Row>
+    idField?: string
+    labelField?: string
+    value?: string | number | null
+    onChange?: (id: string | number, row: Row) => void
+    onCommit?: (id: string | number, row: Row) => void
+    onCancel?: () => void
+    placeholder?: string
+    searchable?: boolean
+    /** Async/remote rows: called (debounced) with the search query; its result
+     *  replaces the list. When set, `options` is only the initial list. */
+    loadOptions?: (query: string) => Promise<Row[]>
+    debounceMs?: number
+    loadingText?: string
+  }
+
+  let {
+    columns,
+    options,
+    idField = 'id',
+    labelField,
+    value = $bindable<string | number | null>(null),
+    onChange,
+    onCommit,
+    onCancel,
+    placeholder = 'Select…',
+    searchable = true,
+    loadOptions,
+    debounceMs = 250,
+    loadingText = 'Loading…',
+    disabled = false,
+    label,
+    hint,
+    error,
+    required = false,
+    invalid = false,
+    size = 'md',
+    id,
+    name,
+    dir,
+    ariaLabel,
+  }: Props = $props()
+
+  const autoId = nextEditorId('sv-gs')
+  const uid = $derived(id ?? autoId)
+  const labelKey = $derived(labelField ?? columns[0]?.field ?? idField)
+  const template = $derived(columns.map((c) => c.width ?? '1fr').join(' '))
+
+  let search = $state('')
+  let triggerEl = $state<HTMLButtonElement | null>(null)
+  let panelEl = $state<HTMLDivElement | null>(null)
+  let searchEl = $state<HTMLInputElement | null>(null)
+  let gridEl = $state<HTMLDivElement | null>(null)
+
+  // Remote/async rows: `asyncRows` holds the last server result; a stale response
+  // is dropped by comparing the request sequence.
+  let asyncRows = $state<Row[]>([])
+  let loading = $state(false)
+  let reqSeq = 0
+  function doLoad(q: string) {
+    if (!loadOptions) return
+    const seq = ++reqSeq
+    loading = true
+    loadOptions(q)
+      .then((rows) => { if (seq === reqSeq) { asyncRows = rows; loading = false } })
+      .catch(() => { if (seq === reqSeq) loading = false })
+  }
+  const runLoad = debounce((q: string) => doLoad(q), debounceMs)
+
+  const filtered = $derived(
+    loadOptions ? asyncRows : filterGridRows(options, columns.map((c) => c.field), search),
+  )
+  // Pool for resolving the selected row's trigger label (a remote-selected id may
+  // not be in the current result page).
+  const pool = $derived(
+    loadOptions ? [...new Map([...options, ...asyncRows].map((r) => [r[idField], r])).values()] : options,
+  )
+  const selectedRow = $derived(pool.find((r) => r[idField] === value) ?? null)
+  const triggerText = $derived(selectedRow ? String(selectedRow[labelKey] ?? '') : '')
+
+  const gs = createPopoverSelect({
+    itemCount: () => filtered.length,
+    onSelect: (i) => {
+      const r = filtered[i]
+      if (r) { value = r[idField] as string | number; onChange?.(r[idField] as string | number, r) }
+    },
+    onOpenChange: (o) => { if (o) { search = ''; if (loadOptions) doLoad('') } },
+    getTrigger: () => triggerEl,
+    getPanel: () => panelEl,
+    getInitialFocus: () => (searchable ? searchEl : gridEl),
+    closeOnSelect: () => true,
+    initialActive: () => Math.max(0, filtered.findIndex((r) => r[idField] === value)),
+    minWidth: () => 320,
+    estimatedHeight: () => 320,
+    idPrefix: 'sv-gs',
+  })
+</script>
+
+<SvField id={uid} {label} {hint} {error} {required} {dir}>
+  <div class="sv-gs sv-gs--{size}" class:is-disabled={disabled}>
+    <button
+      bind:this={triggerEl}
+      type="button"
+      class="sv-gs__trigger"
+      class:is-invalid={invalid}
+      {disabled}
+      onclick={() => gs.toggle()}
+      {...gs.triggerProps()}
+      {...editorAria({ id: uid, invalid, required, error, hint, ariaLabel })}
+    >
+      <span class="sv-gs__value" class:is-placeholder={!triggerText}>{triggerText || placeholder}</span>
+      <span class="sv-gs__arrow" aria-hidden="true">▾</span>
+    </button>
+    {#if name}<input type="hidden" {name} value={value ?? ''} />{/if}
+  </div>
+</SvField>
+
+{#if gs.open}
+  <!-- svelte-ignore a11y_no_static_element_interactions -->
+  <div
+    bind:this={panelEl}
+    class="sv-gs__panel"
+    dir={dir}
+    use:portalToBody
+    use:popIn={{ up: gs.rect.openUpward }}
+    style:position="fixed"
+    style:top={`${gs.rect.top}px`}
+    style:left={`${gs.rect.left}px`}
+    style:min-width={`${Math.max(gs.rect.width, 320)}px`}
+    onkeydown={gs.onPanelKeydown}
+  >
+    {#if searchable}
+      <!-- svelte-ignore a11y_autofocus -->
+      <input
+        bind:this={searchEl}
+        class="sv-gs__search"
+        role="combobox"
+        aria-expanded="true"
+        aria-controls={gs.panelId}
+        aria-activedescendant={gs.activeDescendant()}
+        aria-label="Search options"
+        placeholder="Search…"
+        value={search}
+        oninput={(e) => { search = e.currentTarget.value; gs.active = 0; if (loadOptions) runLoad(search) }}
+      />
+    {/if}
+    <div
+      bind:this={gridEl}
+      id={gs.panelId}
+      class="sv-gs__grid"
+      role="grid"
+      aria-label={label ?? ariaLabel ?? 'Options'}
+      aria-activedescendant={searchable ? undefined : gs.activeDescendant()}
+      tabindex={searchable ? -1 : 0}
+    >
+      <div class="sv-gs__head" role="row" style:grid-template-columns={template}>
+        {#each columns as col (col.field)}
+          <span class="sv-gs__hcell" role="columnheader">{col.header}</span>
+        {/each}
+      </div>
+      <div class="sv-gs__body">
+        {#each filtered as row, i (row[idField])}
+          <div
+            class="sv-gs__row"
+            class:is-active={gs.isActive(i)}
+            class:is-selected={row[idField] === value}
+            role="row"
+            aria-selected={row[idField] === value}
+            style:grid-template-columns={template}
+            onclick={() => { gs.active = i; gs.selectActive() }}
+            {...gs.itemProps(i)}
+          >
+            {#each columns as col (col.field)}
+              <span class="sv-gs__cell" role="gridcell">{String(row[col.field] ?? '')}</span>
+            {/each}
+          </div>
+        {:else}
+          <div class="sv-gs__empty" role="row">{loading ? loadingText : 'No matches'}</div>
+        {/each}
+        {#if loading && filtered.length}
+          <div class="sv-gs__empty" role="row" aria-live="polite">{loadingText}</div>
+        {/if}
+      </div>
+    </div>
+  </div>
+{/if}
+
+<style>
+  .sv-gs { --_accent: var(--sg-accent, #2563eb); display: inline-flex; width: 260px; }
+  .sv-gs.is-disabled { opacity: 0.6; }
+  .sv-gs__trigger {
+    flex: 1; min-width: 0; display: flex; align-items: center; gap: 6px; text-align: start;
+    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; cursor: pointer; padding: 0 9px;
+  }
+  .sv-gs--sm .sv-gs__trigger { height: 28px; font-size: 12px; }
+  .sv-gs--md .sv-gs__trigger { height: 34px; font-size: 13px; }
+  .sv-gs--lg .sv-gs__trigger { height: 40px; font-size: 15px; }
+  .sv-gs__trigger:focus-visible { outline: none; border-color: var(--_accent); box-shadow: 0 0 0 2px color-mix(in srgb, var(--_accent) 22%, transparent); }
+  .sv-gs__trigger.is-invalid { border-color: var(--sg-danger, #dc2626); }
+  .sv-gs__value { flex: 1; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+  .sv-gs__value.is-placeholder { color: var(--sg-muted, #94a3b8); }
+  .sv-gs__arrow { color: var(--sg-muted, #64748b); font-size: 10px; }
+
+  :global(.sv-gs__panel) {
+    z-index: 2147483646; display: flex; flex-direction: column; max-height: 340px; max-width: 92vw; overflow: hidden;
+    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;
+  }
+  :global(.sv-gs__search) {
+    margin: 8px; padding: 6px 9px; font: inherit; font-size: 13px;
+    border: 1px solid var(--sg-input-border, #cbd5e1); border-radius: 7px;
+    background: var(--sg-input-bg, #fff); color: var(--sg-fg, #0f172a); outline: none;
+  }
+  :global(.sv-gs__grid) { display: flex; flex-direction: column; overflow: hidden; outline: none; }
+  :global(.sv-gs__head) {
+    display: grid; gap: 10px; padding: 6px 10px; border-bottom: 1px solid var(--sg-border, #e2e8f0);
+    background: var(--sg-header-bg, #f8fafc); color: var(--sg-header-fg, var(--sg-muted, #64748b));
+    font-size: 11px; font-weight: 650; text-transform: uppercase; letter-spacing: 0.02em;
+  }
+  :global(.sv-gs__body) { overflow: auto; }
+  :global(.sv-gs__row) { display: grid; gap: 10px; padding: 7px 10px; cursor: pointer; align-items: center; }
+  :global(.sv-gs__row.is-active) { background: var(--sg-row-hover-bg, #f1f5f9); }
+  :global(.sv-gs__row.is-selected) { color: var(--sg-accent, #2563eb); font-weight: 600; }
+  :global(.sv-gs__cell) { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+  :global(.sv-gs__empty) { padding: 12px; text-align: center; color: var(--sg-muted, #94a3b8); }
+</style>

package/src/SvGridSelect.test.ts

@@ -0,0 +1,100 @@
+/**
+ * Component tests for SvGridSelect: trigger label, portalled multi-column panel
+ * (header + rows), search filter, and row-click select (emits id + row, closes).
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { mount, unmount, flushSync } from 'svelte'
+import SvGridSelect from './SvGridSelect.svelte'
+
+const columns = [
+  { field: 'name', header: 'Name' },
+  { field: 'email', header: 'Email' },
+  { field: 'role', header: 'Role' },
+]
+const people = [
+  { id: 1, name: 'Ada Lovelace', email: 'ada@x.io', role: 'Eng' },
+  { id: 2, name: 'Alan Turing', email: 'alan@x.io', role: 'Research' },
+  { id: 3, name: 'Grace Hopper', email: 'grace@x.io', role: 'Compilers' },
+]
+
+function mountGs(props: Record<string, unknown>) {
+  const target = document.createElement('div')
+  document.body.appendChild(target)
+  const app = mount(SvGridSelect, { target, props: { columns, options: people, ...props } as any })
+  flushSync()
+  return { target, destroy: () => { unmount(app); target.remove() } }
+}
+
+const bodyRows = () => document.body.querySelectorAll<HTMLElement>('.sv-gs__row')
+
+afterEach(() => { document.body.innerHTML = '' })
+
+describe('SvGridSelect', () => {
+  it('shows the placeholder when nothing is selected', () => {
+    const { target, destroy } = mountGs({ value: null, placeholder: 'Pick a person' })
+    try {
+      expect(target.querySelector('.sv-gs__value')!.textContent).toBe('Pick a person')
+    } finally { destroy() }
+  })
+
+  it('shows the selected row label (default = first column)', () => {
+    const { target, destroy } = mountGs({ value: 2 })
+    try {
+      expect(target.querySelector('.sv-gs__value')!.textContent).toBe('Alan Turing')
+    } finally { destroy() }
+  })
+
+  it('opens a portalled multi-column panel with a header and rows', () => {
+    const { target, destroy } = mountGs({ value: null })
+    try {
+      target.querySelector<HTMLButtonElement>('.sv-gs__trigger')!.click()
+      flushSync()
+      const heads = [...document.body.querySelectorAll('.sv-gs__hcell')].map((h) => h.textContent)
+      expect(heads).toEqual(['Name', 'Email', 'Role'])
+      expect(bodyRows()).toHaveLength(3)
+    } finally { destroy() }
+  })
+
+  it('filters rows via the search box', () => {
+    const { target, destroy } = mountGs({ value: null })
+    try {
+      target.querySelector<HTMLButtonElement>('.sv-gs__trigger')!.click()
+      flushSync()
+      const search = document.body.querySelector<HTMLInputElement>('.sv-gs__search')!
+      search.value = 'turing'
+      search.dispatchEvent(new Event('input', { bubbles: true }))
+      flushSync()
+      expect(bodyRows()).toHaveLength(1)
+      expect(bodyRows()[0]!.textContent).toContain('Alan Turing')
+    } finally { destroy() }
+  })
+
+  it('clicking a row emits (id, row) and closes', () => {
+    const onChange = vi.fn()
+    const { target, destroy } = mountGs({ value: null, onChange })
+    try {
+      target.querySelector<HTMLButtonElement>('.sv-gs__trigger')!.click()
+      flushSync()
+      bodyRows()[2]!.click() // Grace
+      flushSync()
+      expect(onChange).toHaveBeenCalledWith(3, people[2])
+      expect(document.body.querySelector('.sv-gs__panel')).toBeNull()
+    } finally { destroy() }
+  })
+
+  it('loads remote rows via loadOptions when opened', async () => {
+    const loadOptions = vi.fn(async () => [
+      { id: 9, name: 'Remote Person', email: 'r@x.io', role: 'Remote' },
+    ])
+    const { target, destroy } = mountGs({ value: null, loadOptions })
+    try {
+      target.querySelector<HTMLButtonElement>('.sv-gs__trigger')!.click()
+      flushSync()
+      expect(loadOptions).toHaveBeenCalledWith('')
+      await vi.waitFor(() => {
+        flushSync()
+        expect([...bodyRows()].map((r) => r.textContent).join()).toContain('Remote Person')
+      })
+    } finally { destroy() }
+  })
+})

package/src/SvGroupCell.svelte

@@ -0,0 +1,109 @@
+<!--
+  Built-in group cell for the server-side group/tree model. Drop it into the
+  grouping column and it draws the expander + indentation for group rows (and an
+  indented leaf value) - no hand-written cell recipe. Pair with `serverGroupRows`
+  to feed `<SvGrid data>`, and wire `onToggle` to the controller's `toggleGroup`.
+
+      cell: (ctx) => renderComponent(SvGroupCell, {
+        row: ctx.row.original, onToggle: ctl.toggleGroup, leafField: 'name',
+      })
+-->
+<script lang="ts" generics="TData">
+  import type { ServerDisplayRow } from './server-data-source'
+
+  type GroupGridRow = { __group?: ServerDisplayRow<TData> } & Record<string, unknown>
+  type Props = {
+    /** The grid row from `serverGroupRows` (carries the `__group` marker). */
+    row: GroupGridRow
+    /**
+     * Expand / collapse a group, or load more children. Receives the grid row;
+     * wire to `serverGroupNav(ctl).onToggle` (which drives clicks and keyboard).
+     */
+    onToggle: (row: GroupGridRow) => void
+    /** Field to show for leaf rows in the group column (blank if omitted). */
+    leafField?: string
+    /** Pixels of indentation per level. Default 18. */
+    indent?: number
+  }
+
+  let { row, onToggle, leafField, indent = 18 }: Props = $props()
+  const meta = $derived(row.__group)
+</script>
+
+{#if meta && meta.kind === 'group'}
+  <button
+    type="button"
+    class="sv-group-cell"
+    style={`padding-left: ${meta.level * indent}px`}
+    aria-expanded={meta.expanded}
+    aria-label={meta.expanded ? 'Collapse group' : 'Expand group'}
+    onclick={() => onToggle(row)}
+  >
+    <span class="sv-group-chev" class:open={meta.expanded} aria-hidden="true">▸</span>
+    <span class="sv-group-key">{meta.key}</span>
+    {#if meta.loading}<span class="sv-group-load" aria-hidden="true">…</span>{/if}
+  </button>
+{:else if meta && meta.kind === 'more'}
+  <button
+    type="button"
+    class="sv-group-more"
+    style={`padding-left: ${meta.level * indent}px`}
+    disabled={meta.loading}
+    onclick={() => onToggle(row)}
+  >
+    {meta.loading ? 'Loading...' : `Load ${meta.remaining} more`}
+  </button>
+{:else if meta && meta.kind === 'footer'}
+  <span class="sv-group-footer" style={`padding-left: ${meta.level * indent}px`}>Total</span>
+{:else if meta && meta.kind === 'skeleton'}
+  <span class="sv-group-skeleton" style={`margin-left: ${meta.level * indent}px`} aria-hidden="true"></span>
+{:else if meta}
+  <span class="sv-group-leaf" style={`padding-left: ${(meta.level + 1) * indent}px`}>
+    {leafField ? (row[leafField] ?? '') : ''}
+  </span>
+{/if}
+
+<style>
+  .sv-group-cell {
+    display: inline-flex;
+    align-items: center;
+    gap: 6px;
+    background: none;
+    border: 0;
+    padding: 0;
+    font: inherit;
+    color: inherit;
+    cursor: pointer;
+  }
+  .sv-group-chev {
+    display: inline-block;
+    transition: transform 0.15s;
+    color: var(--sg-muted, #64748b);
+  }
+  .sv-group-chev.open { transform: rotate(90deg); }
+  .sv-group-key { font-weight: 600; }
+  .sv-group-load { color: var(--sg-muted, #64748b); font-size: 12px; }
+  .sv-group-leaf { color: var(--sg-muted, #475569); }
+  .sv-group-more {
+    background: none;
+    border: 0;
+    padding: 0;
+    font: inherit;
+    font-size: 13px;
+    color: var(--sg-accent, #2563eb);
+    cursor: pointer;
+  }
+  .sv-group-more:disabled { color: var(--sg-muted, #64748b); cursor: default; }
+  .sv-group-footer { font-weight: 600; color: var(--sg-muted, #64748b); font-size: 12px; text-transform: uppercase; letter-spacing: 0.03em; }
+  .sv-group-skeleton {
+    display: inline-block;
+    width: 60%;
+    height: 10px;
+    border-radius: 5px;
+    background: linear-gradient(90deg, var(--sg-border, #e2e8f0) 25%, var(--sg-header-bg, #f1f5f9) 50%, var(--sg-border, #e2e8f0) 75%);
+    background-size: 200% 100%;
+    animation: sv-group-shimmer 1.2s infinite;
+  }
+  @keyframes sv-group-shimmer { from { background-position: 200% 0; } to { background-position: -200% 0; } }
+  @media (prefers-reduced-motion: reduce) { .sv-group-skeleton { animation: none; } }
+</style>

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>