@svgrid/grid 2.2.16 → 2.2.18

package/src/group-display.ts

@@ -0,0 +1,117 @@
+/**
+ * Row-grouping display helpers. Two pure, framework-free transforms:
+ *
+ * - `insertGroupFooters` inserts a footer/total row after each group's children
+ *   (and optionally a grand-total row at the end), carrying the group's already
+ *   computed aggregate values. Mirrors the server model's footer shape
+ *   (`server-group-model.ts`) client-side.
+ * - `buildAutoGroupColumns` decides, for a grouping display mode, which synthetic
+ *   "auto group" columns to show and which grouped source columns to hide - the
+ *   groundwork for `singleColumn` / `multipleColumns` display types (the current
+ *   default `groupRows` renders a full-width banner and needs neither).
+ *
+ * Both are generic over the row / column shape (via small accessor callbacks) so
+ * they are trivially unit-testable and carry no dependency on the grid runtime.
+ */
+
+/** AG-Grid-style grouping display variants. */
+export type GroupDisplayType = 'groupRows' | 'singleColumn' | 'multipleColumns'
+
+export type GroupFooterOptions<R> = {
+  /** Depth of a row (group rows and their descendants). */
+  getDepth: (row: R) => number
+  /** True when a row is a group (banner) row. */
+  isGroup: (row: R) => boolean
+  /** Build a footer row from the group row it closes (carries its aggregates). */
+  makeFooter: (groupRow: R) => R
+  /** Insert a footer after each group's children. */
+  includeGroupFooter?: boolean
+  /** Append a grand-total footer at the very end. */
+  includeGrandTotalFooter?: boolean
+  /** Build the grand-total footer (over the whole set). Return null to skip. */
+  makeGrandTotal?: () => R | null
+}
+
+/**
+ * Insert group footer rows after each group's descendants. A group opened at
+ * depth d closes when a later row appears at depth <= d (a sibling group or an
+ * ancestor-level row); its footer is emitted at that point. Order is otherwise
+ * preserved. No-op when neither footer flag is set.
+ */
+export function insertGroupFooters<R>(rows: ReadonlyArray<R>, opts: GroupFooterOptions<R>): R[] {
+  const { getDepth, isGroup, makeFooter, includeGroupFooter, includeGrandTotalFooter, makeGrandTotal } = opts
+  if (!includeGroupFooter && !includeGrandTotalFooter) return [...rows]
+
+  const out: R[] = []
+  const openGroups: R[] = []
+
+  const closeTo = (depth: number) => {
+    while (openGroups.length > 0) {
+      const top = openGroups[openGroups.length - 1]!
+      if (getDepth(top) < depth) break
+      openGroups.pop()
+      if (includeGroupFooter) out.push(makeFooter(top))
+    }
+  }
+
+  for (const row of rows) {
+    // Before adding this row, close any groups it ends (same-or-shallower depth).
+    closeTo(getDepth(row))
+    out.push(row)
+    if (isGroup(row)) openGroups.push(row)
+  }
+  // Close everything still open at the end.
+  closeTo(Number.NEGATIVE_INFINITY)
+
+  if (includeGrandTotalFooter && makeGrandTotal) {
+    const gt = makeGrandTotal()
+    if (gt != null) out.push(gt)
+  }
+  return out
+}
+
+export type AutoGroupColumnSpec = {
+  /** Synthetic column id (e.g. `__autoGroup` or `__group_<field>`). */
+  id: string
+  /** The grouped field this auto column stands in for (null for the single
+   *  combined auto-group column). */
+  field: string | null
+  /** Nesting level this column represents (0-based), for indentation. */
+  level: number
+}
+
+export type AutoGroupResult = {
+  /** Synthetic auto-group column specs to prepend to the visible columns. */
+  autoColumns: AutoGroupColumnSpec[]
+  /** Ids of the grouped SOURCE columns to hide (rolled into the auto columns). */
+  hiddenSourceIds: Set<string>
+}
+
+/**
+ * Decide the synthetic auto-group columns for a grouping display mode:
+ * - `groupRows`: none (the banner path handles display) - `{ [], {} }`.
+ * - `singleColumn`: one combined auto-group column; every grouped source column
+ *   is hidden.
+ * - `multipleColumns`: one auto column per grouped field; the grouped source
+ *   columns are hidden.
+ */
+export function buildAutoGroupColumns(
+  grouping: ReadonlyArray<string>,
+  displayType: GroupDisplayType,
+): AutoGroupResult {
+  if (displayType === 'groupRows' || grouping.length === 0) {
+    return { autoColumns: [], hiddenSourceIds: new Set() }
+  }
+  const hiddenSourceIds = new Set(grouping)
+  if (displayType === 'singleColumn') {
+    return {
+      autoColumns: [{ id: '__autoGroup', field: null, level: 0 }],
+      hiddenSourceIds,
+    }
+  }
+  // multipleColumns
+  return {
+    autoColumns: grouping.map((field, level) => ({ id: `__group_${field}`, field, level })),
+    hiddenSourceIds,
+  }
+}

package/src/i18n.grid.test.ts

@@ -0,0 +1,73 @@
+/**
+ * DOM: `localeText` translates the grid's chrome strings (empty state, pager,
+ * tool panel) while leaving everything else English.
+ */
+import { afterEach, describe, expect, it } from 'vitest'
+import { mount, unmount } from 'svelte'
+import SvGrid from './SvGrid.svelte'
+import {
+  createCoreRowModel,
+  createFilteredRowModel,
+  createPaginatedRowModel,
+  createSortedRowModel,
+  sortFns,
+  tableFeatures,
+  rowSortingFeature,
+} from './index'
+import type { ColumnDef } from './index'
+
+type Row = { id: number; name: string }
+const features = tableFeatures({ rowSortingFeature })
+const cols: ColumnDef<typeof features, Row>[] = [{ field: 'name', header: 'Name', width: 160 }]
+
+const tick = () => new Promise<void>((r) => queueMicrotask(r))
+
+function mountGrid(props: Record<string, unknown>) {
+  const target = document.createElement('div')
+  document.body.appendChild(target)
+  const app = mount(SvGrid, {
+    target,
+    props: {
+      columns: cols,
+      features,
+      _rowModels: {
+        coreRowModel: createCoreRowModel(),
+        filteredRowModel: createFilteredRowModel(),
+        sortedRowModel: createSortedRowModel(sortFns),
+        paginatedRowModel: createPaginatedRowModel(),
+      },
+      containerHeight: 240,
+      virtualization: false,
+      ...props,
+    } as never,
+  })
+  return { target, destroy: () => { unmount(app); target.remove() } }
+}
+
+let cleanup: (() => void) | null = null
+afterEach(() => { cleanup?.(); cleanup = null })
+
+describe('localeText', () => {
+  it('translates the empty-state message', async () => {
+    const { target, destroy } = mountGrid({ data: [], localization: { text: { noRows: 'Aucune ligne a afficher' } } })
+    cleanup = destroy
+    await tick()
+    expect(target.textContent).toContain('Aucune ligne a afficher')
+    expect(target.textContent).not.toContain('No rows to display')
+  })
+
+  it('translates the pager while leaving unset strings English', async () => {
+    const data: Row[] = Array.from({ length: 12 }, (_, i) => ({ id: i, name: `n${i}` }))
+    const { target, destroy } = mountGrid({
+      data,
+      showPagination: true,
+      pageSize: 5,
+      localization: { text: { pageSize: 'Taille de page :', page: 'Page FR' } },
+    })
+    cleanup = destroy
+    await tick()
+    await tick()
+    expect(target.textContent).toContain('Taille de page :')
+    expect(target.textContent).toContain('Page FR')
+  })
+})

package/src/index.ts

@@ -69,8 +69,24 @@ export { createGrid, createSvGrid, type SvelteGrid } from './createGrid.svelte'
 export { createGridState, createSvGridState } from './createGridState.svelte'
 export { subscribeGrid, subscribeSvGrid } from './subscribe'
 export { default as SvGrid } from './SvGrid.svelte'
-export { default as SvGridBoard } from './SvGridBoard.svelte'
+// Kanban board view. The `board` prop + its config types live in the free grid,
+// but the RENDERER (SvGridBoard) ships in @svgrid/enterprise and registers itself
+// through this seam (see board-view.svelte.ts). Mirrors the scheduler-view seam.
 export type { BoardConfig, BoardLane, BoardCardMoveEvent, BoardCardCommitEvent, BoardLayout, BoardSubtask, BoardComment, BoardMenuContext, BoardLaneMenuContext, BoardDrawerConfig } from './SvGrid.types'
+export { registerBoardView, getBoardView, hasBoardView } from './board-view.svelte'
+// Built-in AI helpers (free): natural-language filter, smart-fill, summarize,
+// classify, anomaly detection, chart-this and export planning. They ship no
+// model client and no-op until you register one with `setAIProvider(...)`, so
+// they tree-shake out of the base bundle unless you actually import them. The
+// export-provider seam lets @svgrid/enterprise register its Excel/PDF engine so
+// AI-planned exports can WRITE those formats.
+export * from './ai'
+export {
+  registerExportProvider,
+  getExportProvider,
+  type GridExportProvider,
+  type GridExportRunOptions,
+} from './export-provider'
 // Scheduler / calendar view. The `scheduler` prop + its config types live in
 // the free grid, but the RENDERER ships in @svgrid/enterprise and registers
 // itself through this seam (see scheduler-view.svelte.ts). Mirrors editor-registry.
@@ -89,6 +105,20 @@ export type {
   SchedulerOccurrenceChangeEvent,
 } from './SvGrid.types'
 export { registerSchedulerView, getSchedulerView, hasSchedulerView } from './scheduler-view.svelte'
+// Chart view. The `chart` prop + its config live in the free grid AND so does the
+// renderer (SvGridChartView wraps the free SvChart) - so unlike board/scheduler
+// it works out of the box. This seam only lets a host OVERRIDE the built-in view.
+export type { ChartViewConfig } from './SvGrid.types'
+export { registerChartView, getChartView, hasChartView } from './chart-view.svelte'
+export {
+  registerPivotEngine,
+  getPivotEngine,
+  hasPivotEngine,
+  type PivotEngine,
+  type GridPivotConfig,
+  type GridPivotValue,
+  type GridPivotRow,
+} from './pivot-view.svelte'
 // Pure scheduler layout/model helpers (framework-free, like recurrence/date-core).
 // The calendar RENDERER that consumes these ships in @svgrid/enterprise.
 export {
@@ -147,6 +177,7 @@ export {
   type SvEditorProps,
   type EditorSize,
   type EditorDir,
+  type EditorAction,
   type EditorAriaState,
 } from './editor-contract'
 // UI kit - editor interaction surface (commit/cancel/close for grid-cell use)
@@ -183,7 +214,26 @@ export { createCarousel, type Carousel, type CarouselConfig } from './createCaro
 // createOverlay for the focus-trap/scroll-lock/dismissal lifecycle.
 export { createCommand, type Command, type CommandConfig } from './createCommand.svelte'
 // Schema-driven form core (SvForm): values/errors/touched + validation + submit.
-export { createForm, type Form, type FormConfig } from './createForm.svelte'
+export { createForm, type Form, type FormConfig, type FormMessages } from './createForm.svelte'
+export { default as SvSegmented, type SegmentedOption } from './SvSegmented.svelte'
+export { default as SvSpinner } from './SvSpinner.svelte'
+export { default as SvLoadingOverlay } from './SvLoadingOverlay.svelte'
+export { default as SvResult } from './SvResult.svelte'
+export { default as SvCollapsible } from './SvCollapsible.svelte'
+export { default as SvStack } from './SvStack.svelte'
+export { default as SvGroup } from './SvGroup.svelte'
+export { default as SvSimpleGrid } from './SvSimpleGrid.svelte'
+// UI kit - typography + display primitives (Pillar C2)
+export { default as SvText } from './SvText.svelte'
+export { default as SvTitle } from './SvTitle.svelte'
+export { default as SvAnchor } from './SvAnchor.svelte'
+export { default as SvBlockquote } from './SvBlockquote.svelte'
+export { default as SvMark } from './SvMark.svelte'
+export { default as SvList } from './SvList.svelte'
+export { default as SvKbd } from './SvKbd.svelte'
+export { default as SvCode } from './SvCode.svelte'
+export { default as SvVisuallyHidden } from './SvVisuallyHidden.svelte'
+export { default as SvAspectRatio } from './SvAspectRatio.svelte'
 // UI kit - custom cell-editor registry (register any component as a grid editor)
 export {
   registerCellEditor,
@@ -395,6 +445,7 @@ export { default as SvContextMenu } from './SvContextMenu.svelte'
 export {
   toast,
   dismissToast,
+  updateToast,
   clearToasts,
   pauseToast,
   resumeToast,
@@ -403,9 +454,15 @@ export {
   type ToastVariant,
   type ToastOptions,
   type ToastFn,
+  type ToastAction,
+  type UpdateToast,
+  type PromiseMessages,
 } from './toast-store.svelte'
 export { default as SvMenu, type MenuItem } from './SvMenu.svelte'
 export { default as SvMenuList } from './SvMenuList.svelte'
+export { default as SvMenubar, type MenubarMenu } from './SvMenubar.svelte'
+export { default as SvHoverCard } from './SvHoverCard.svelte'
+export { default as SvPopconfirm } from './SvPopconfirm.svelte'
 export { default as SvNavPane, type NavItem, type NavSection, type NavModule } from './SvNavPane.svelte'
 export { default as SvProgress } from './SvProgress.svelte'
 export { default as SvCircularProgress } from './SvCircularProgress.svelte'
@@ -413,6 +470,18 @@ export { popIn } from './popover'
 export { default as SvForm, type FormField, type FormFieldType, type FormSection, type FormEntry } from './SvForm.svelte'
 export { rules, runRules, isEmptyValue, type Validator, type RuleOptions, type CompareOp } from './validators'
 export { anchoredRect, portalToBody, PANEL_THEME_VARS, type AnchoredRect } from './popover'
+export {
+  computePosition,
+  autoUpdate,
+  parsePlacement,
+  type Placement,
+  type Side,
+  type Align,
+  type Rect,
+  type Viewport,
+  type ComputePositionOptions,
+  type ComputePositionResult,
+} from './positioning'
 export {
   toDate, startOfDay, startOfWeek, startOfMonth, addDays, addMonths, addYears, clampDate, isSameDay,
   monthMatrix, weekdayOrder, isoWeek, decadeRange, withTime, snapMinute, type DateLike,
@@ -434,7 +503,14 @@ export { default as FlexRender } from './FlexRender.svelte'
 export { renderComponent, renderSnippet } from './render-component'
 export { default as SvGridChart } from './SvGridChart.svelte'
 export { default as SvGridChartPanel } from './SvGridChartPanel.svelte'
+// Preferred names for the standalone chart primitives. `SvChart` is a genuine
+// standalone component (spec-driven, no grid needed), so it sits alongside its
+// unprefixed siblings SvGauge / SvSparkline. The `SvGrid*` names remain exported
+// as aliases so existing imports keep working.
+export { default as SvChart } from './SvGridChart.svelte'
+export { default as SvChartPanel } from './SvGridChartPanel.svelte'
 export type { ChartingConfig, ChartAggregateRequest, ChartAggregateBucket } from './SvGrid.types'
+export type { GridLocalization } from './SvGrid.types'
 export {
   buildChart,
   formatChartValue,
@@ -585,6 +661,19 @@ export {
   type RuleFormat,
   type ResolvedCellFormat,
 } from './conditional-formatting'
+export {
+  defaultGridMessages,
+  resolveGridMessages,
+  type GridMessages,
+} from './grid-messages'
+export {
+  insertGroupFooters,
+  buildAutoGroupColumns,
+  type GroupDisplayType,
+  type GroupFooterOptions,
+  type AutoGroupColumnSpec,
+  type AutoGroupResult,
+} from './group-display'
 export { getKeyboardIntent, getNextActiveCell, type GridKeyboardIntent } from './keyboard'
 export { createVirtualizer } from './virtualization/virtualizer'
 export { createSvelteVirtualizer } from './virtualization/svelte-virtualizer.svelte'

package/src/js-scroller.svelte.ts

@@ -0,0 +1,173 @@
+/**
+ * createJsScroller - a JS-driven vertical scroller for the virtualized selection
+ * controls (SvListBox / SvDropDownList / SvTree).
+ *
+ * Native overflow scroll is composited off the main thread, so on a fast
+ * scrollbar-thumb drag the browser paints the new (empty) scroll position a
+ * frame before JS can re-window the virtualizer - the "blank flash while
+ * scrolling". This helper removes that async gap the way Smart's list does: the
+ * content does NOT use native scroll. A single `scrollOffset` state positions
+ * the rows (`translateY`) AND drives the virtualizer window in the same reactive
+ * flush, and a custom scrollbar + wheel/touch handlers set that offset directly.
+ *
+ * The component owns the markup (translated rows + the `sb`/`thumb` elements);
+ * this owns the offset, the geometry, and the input handlers.
+ */
+import { untrack } from 'svelte'
+
+type ScrollerVirtualizer = {
+  setScrollOffset: (offset: number) => void
+  getOffsetForIndex: (index: number) => number
+  getSizeForIndex: (index: number) => number
+}
+
+export type JsScrollerConfig = {
+  /** The shared virtualizer to drive. */
+  virtualizer: ScrollerVirtualizer
+  /** Full scrollable content height (px). */
+  totalSize: () => number
+  /** Visible viewport height (px). */
+  viewport: () => number
+  /** Row height used to convert line-mode wheel deltas to px. */
+  lineStep: () => number
+}
+
+export function createJsScroller(cfg: JsScrollerConfig) {
+  // The single source of truth for the scroll position.
+  let scrollOffset = $state(0)
+  const maxOffset = $derived(Math.max(0, cfg.totalSize() - cfg.viewport()))
+
+  // Push the offset into the virtualizer whenever it changes. `untrack` keeps
+  // the virtualizer's `version` write out of this effect's dependencies.
+  $effect(() => {
+    const o = scrollOffset
+    untrack(() => cfg.virtualizer.setScrollOffset(o))
+  })
+  // Re-clamp if the content shrinks under the current offset.
+  $effect(() => {
+    const m = maxOffset
+    if (untrack(() => scrollOffset) > m) scrollOffset = m
+  })
+
+  function scrollTo(offset: number) {
+    scrollOffset = Math.max(0, Math.min(maxOffset, offset))
+  }
+  function scrollByPx(delta: number) {
+    scrollTo(scrollOffset + delta)
+  }
+
+  function onWheel(e: WheelEvent) {
+    if (maxOffset <= 0) return
+    // deltaMode: 0 = pixels, 1 = lines, 2 = pages.
+    const step =
+      e.deltaMode === 1 ? e.deltaY * cfg.lineStep() : e.deltaMode === 2 ? e.deltaY * cfg.viewport() : e.deltaY
+    const before = scrollOffset
+    scrollByPx(step)
+    // Only swallow the wheel when it moved us, so the page can scroll once the
+    // list is pinned at its top/bottom edge.
+    if (scrollOffset !== before) e.preventDefault()
+  }
+
+  // --- Custom scrollbar geometry --------------------------------------------
+  const thumbH = $derived(
+    maxOffset > 0 && cfg.totalSize() > 0
+      ? Math.max(24, Math.min(cfg.viewport(), (cfg.viewport() / cfg.totalSize()) * cfg.viewport()))
+      : 0,
+  )
+  const trackRange = $derived(Math.max(0, cfg.viewport() - thumbH))
+  const thumbTop = $derived(maxOffset > 0 ? (scrollOffset / maxOffset) * trackRange : 0)
+
+  let dragging = $state(false)
+  let dragStartY = 0
+  let dragStartOffset = 0
+  function onThumbDown(e: PointerEvent) {
+    e.stopPropagation()
+    e.preventDefault()
+    dragging = true
+    dragStartY = e.clientY
+    dragStartOffset = scrollOffset
+    ;(e.currentTarget as HTMLElement).setPointerCapture(e.pointerId)
+  }
+  function onThumbMove(e: PointerEvent) {
+    if (!dragging) return
+    const dy = e.clientY - dragStartY
+    scrollTo(dragStartOffset + (trackRange > 0 ? (dy / trackRange) * maxOffset : 0))
+  }
+  function onThumbUp(e: PointerEvent) {
+    dragging = false
+    releaseCapture(e)
+  }
+  function onTrackDown(e: PointerEvent) {
+    const rect = (e.currentTarget as HTMLElement).getBoundingClientRect()
+    scrollByPx(e.clientY - rect.top < thumbTop ? -cfg.viewport() : cfg.viewport())
+  }
+
+  // --- Touch: drag the content to pan ---------------------------------------
+  let touchActive = false
+  let touchStartY = 0
+  let touchStartOffset = 0
+  function onContentDown(e: PointerEvent) {
+    if (e.pointerType !== 'touch') return
+    touchActive = true
+    touchStartY = e.clientY
+    touchStartOffset = scrollOffset
+    ;(e.currentTarget as HTMLElement).setPointerCapture(e.pointerId)
+  }
+  function onContentMove(e: PointerEvent) {
+    if (!touchActive) return
+    scrollTo(touchStartOffset - (e.clientY - touchStartY))
+  }
+  function onContentUp(e: PointerEvent) {
+    if (!touchActive) return
+    touchActive = false
+    releaseCapture(e)
+  }
+
+  function releaseCapture(e: PointerEvent) {
+    try {
+      ;(e.currentTarget as HTMLElement).releasePointerCapture(e.pointerId)
+    } catch {
+      /* capture may already be gone */
+    }
+  }
+
+  /** Scroll the minimal amount to bring `[top, top+h]` fully into view. */
+  function ensureVisible(top: number, h: number) {
+    if (top < scrollOffset) scrollTo(top)
+    else if (top + h > scrollOffset + cfg.viewport()) scrollTo(top + h - cfg.viewport())
+  }
+  /** Bring a virtualizer row index into view (variable-height aware). */
+  function ensureIndexVisible(index: number) {
+    ensureVisible(cfg.virtualizer.getOffsetForIndex(index), cfg.virtualizer.getSizeForIndex(index))
+  }
+
+  return {
+    get scrollOffset() {
+      return scrollOffset
+    },
+    get maxOffset() {
+      return maxOffset
+    },
+    get thumbH() {
+      return thumbH
+    },
+    get thumbTop() {
+      return thumbTop
+    },
+    get dragging() {
+      return dragging
+    },
+    scrollTo,
+    scrollByPx,
+    ensureVisible,
+    ensureIndexVisible,
+    onWheel,
+    onThumbDown,
+    onThumbMove,
+    onThumbUp,
+    onTrackDown,
+    onContentDown,
+    onContentMove,
+    onContentUp,
+  }
+}

package/src/list-option.test.ts

@@ -0,0 +1,56 @@
+/**
+ * Tests for the option-list helpers, focused on `flattenForVirtual` - the pure
+ * model that lets the selection controls window a GROUPED list and mix row
+ * heights, reusing the shared virtualizer.
+ */
+import { describe, expect, it } from 'vitest'
+import { flattenForVirtual, normalizeOptions, type ListOption } from './list-option'
+
+describe('flattenForVirtual', () => {
+  it('passes an ungrouped list through as option rows (uniform height)', () => {
+    const options = normalizeOptions([1, 2, 3])
+    const m = flattenForVirtual(options, { rowHeight: 32 })
+    expect(m.hasGroups).toBe(false)
+    expect(m.entries).toHaveLength(3)
+    expect(m.entries.every((e) => e.type === 'option')).toBe(true)
+    expect(m.entries.map((e) => e.size)).toEqual([32, 32, 32])
+    // Ungrouped: option index === flat index.
+    expect(m.optionFlatIndex).toEqual([0, 1, 2])
+    expect(m.sizeAt(1)).toBe(32)
+  })
+
+  it('interleaves group heading rows and keeps option->flat mapping', () => {
+    const options: ListOption[] = [
+      { value: 'a', label: 'A', group: 'G1' },
+      { value: 'b', label: 'B', group: 'G1' },
+      { value: 'c', label: 'C', group: 'G2' },
+    ]
+    const m = flattenForVirtual(options, { rowHeight: 30, groupHeaderHeight: 20 })
+    expect(m.hasGroups).toBe(true)
+    // [G1 header, a, b, G2 header, c]
+    expect(m.entries.map((e) => e.type)).toEqual(['group', 'option', 'option', 'group', 'option'])
+    expect(m.entries.map((e) => e.size)).toEqual([20, 30, 30, 20, 30])
+    // Option indices 0,1,2 land at flat rows 1,2,4.
+    expect(m.optionFlatIndex).toEqual([1, 2, 4])
+    expect(m.entries[0]).toMatchObject({ type: 'group', label: 'G1' })
+  })
+
+  it('supports a per-option variable height function', () => {
+    const options = normalizeOptions(['x', 'y', 'z'])
+    const m = flattenForVirtual(options, { rowHeight: (_opt, i) => 20 + i * 10 })
+    expect(m.entries.map((e) => e.size)).toEqual([20, 30, 40])
+    expect(m.sizeAt(2)).toBe(40)
+  })
+
+  it('clamps non-positive heights to at least 1px', () => {
+    const options = normalizeOptions(['x'])
+    const m = flattenForVirtual(options, { rowHeight: 0, groupHeaderHeight: 0 })
+    expect(m.sizeAt(0)).toBe(1)
+  })
+
+  it('is empty for no options', () => {
+    const m = flattenForVirtual([], { rowHeight: 32 })
+    expect(m.entries).toEqual([])
+    expect(m.optionFlatIndex).toEqual([])
+  })
+})

package/src/list-option.ts

@@ -9,6 +9,25 @@ export type ListOption = {
   color?: string
 }
 
+/**
+ * Coerce a raw options array into well-formed ListOptions. A primitive item
+ * (`1`, `'a'`) becomes `{ value, label: String(value) }`; an object missing a
+ * `label` or `value` gets the other filled in. This makes a caller who passes
+ * e.g. `[1, 2, 3]` or `['a', 'b']` render sensibly instead of crashing a keyed
+ * `#each` on `undefined`/duplicate `value`s.
+ */
+export function normalizeOptions(raw: ReadonlyArray<ListOption | string | number> | null | undefined): ListOption[] {
+  if (!raw) return []
+  return raw.map((o) => {
+    if (o != null && typeof o === 'object') {
+      const opt = o as Partial<ListOption>
+      const value = opt.value ?? opt.label ?? ''
+      return { ...(opt as ListOption), value, label: opt.label ?? String(value) }
+    }
+    return { value: o, label: String(o) }
+  })
+}
+
 /** Case-insensitive substring filter over option labels. */
 export function filterOptions(options: ReadonlyArray<ListOption>, query: string): ListOption[] {
   const q = query.trim().toLowerCase()
@@ -44,6 +63,68 @@ export function hasGroups(options: ReadonlyArray<ListOption>): boolean {
   return options.some((o) => o.group != null)
 }
 
+/** Fixed px, or a per-option function - lets a virtualized list mix row heights. */
+export type RowHeight = number | ((opt: IndexedOption, index: number) => number)
+
+/** One row of the flattened virtualization model: a group heading or an option. */
+export type VirtualListRow =
+  | { type: 'group'; label: string; size: number }
+  | { type: 'option'; opt: IndexedOption; size: number }
+
+export type FlatVirtualModel = {
+  /** Group headings + options in render order, each with its px height. */
+  entries: VirtualListRow[]
+  /** Whether any group heading rows are present. */
+  hasGroups: boolean
+  /** Height (px) of the entry at flat index `i` - feeds the virtualizer's `estimateSize`. */
+  sizeAt: (i: number) => number
+  /** Maps an OPTION index (position in the source options array, as used by
+   *  `optionProps(index)`) to its flat entry index - so the active option can
+   *  be scrolled into view even with group rows interleaved. */
+  optionFlatIndex: number[]
+}
+
+/**
+ * Flatten a (possibly grouped) option list into a single virtualization model:
+ * group headings become rows interleaved with their options, and each row
+ * carries its pixel height. This is what lets the selection controls window a
+ * GROUPED list (previously they fell back to rendering every node) and support
+ * variable row heights, while reusing the shared `createSvelteVirtualizer`.
+ *
+ * Pure - no DOM. Builds on `groupOptions`, which already tags each option with
+ * its flat `index` (the value `optionProps(index)` expects).
+ */
+export function flattenForVirtual(
+  options: ReadonlyArray<ListOption>,
+  opts: { rowHeight: RowHeight; groupHeaderHeight?: number },
+): FlatVirtualModel {
+  const headerH = Math.max(1, opts.groupHeaderHeight ?? 28)
+  const rh = opts.rowHeight
+  const sizeOf = (o: IndexedOption) => Math.max(1, typeof rh === 'function' ? rh(o, o.index) : rh)
+
+  const entries: VirtualListRow[] = []
+  const optionFlatIndex = new Array<number>(options.length)
+  let anyGroups = false
+
+  for (const g of groupOptions(options)) {
+    if (g.group != null) {
+      anyGroups = true
+      entries.push({ type: 'group', label: g.group, size: headerH })
+    }
+    for (const opt of g.options) {
+      optionFlatIndex[opt.index] = entries.length
+      entries.push({ type: 'option', opt, size: sizeOf(opt) })
+    }
+  }
+
+  return {
+    entries,
+    hasGroups: anyGroups,
+    sizeAt: (i) => entries[i]?.size ?? 0,
+    optionFlatIndex,
+  }
+}
+
 /**
  * Next enabled option index whose label starts with `buffer` (type-ahead),
  * searching forward from just after `from` and wrapping. Returns -1 for no