@svgrid/grid 1.2.34 → 2.0.0

package/dist/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/dist/SvGridSelect.svelte.d.ts

@@ -0,0 +1,32 @@
+export type { GridSelectColumn } from './ui-app.types';
+/**
+   * 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 { type SvEditorProps } from './editor-contract';
+import { 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;
+};
+declare const SvGridSelect: import("svelte").Component<Props, {}, "value">;
+type SvGridSelect = ReturnType<typeof SvGridSelect>;
+export default SvGridSelect;

package/dist/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/dist/SvGroupCell.svelte.d.ts

@@ -0,0 +1,41 @@
+import type { ServerDisplayRow } from './server-data-source';
+declare function $$render<TData>(): {
+    props: {
+        /** The grid row from `serverGroupRows` (carries the `__group` marker). */
+        row: {
+            __group?: ServerDisplayRow<TData>;
+        } & Record<string, unknown>;
+        /**
+         * Expand / collapse a group, or load more children. Receives the grid row;
+         * wire to `serverGroupNav(ctl).onToggle` (which drives clicks and keyboard).
+         */
+        onToggle: (row: {
+            __group?: ServerDisplayRow<TData>;
+        } & Record<string, unknown>) => 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;
+    };
+    exports: {};
+    bindings: "";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<TData> {
+    props(): ReturnType<typeof $$render<TData>>['props'];
+    events(): ReturnType<typeof $$render<TData>>['events'];
+    slots(): ReturnType<typeof $$render<TData>>['slots'];
+    bindings(): "";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <TData>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<TData>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<TData>['props']>, ReturnType<__sveltets_Render<TData>['events']>, ReturnType<__sveltets_Render<TData>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<TData>['bindings']>;
+    } & ReturnType<__sveltets_Render<TData>['exports']>;
+    <TData>(internal: unknown, props: ReturnType<__sveltets_Render<TData>['props']> & {}): ReturnType<__sveltets_Render<TData>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+declare const SvGroupCell: $$IsomorphicComponent;
+type SvGroupCell<TData> = InstanceType<typeof SvGroupCell<TData>>;
+export default SvGroupCell;

package/dist/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>