@svgrid/grid 2.1.22 → 2.1.23

package/src/SvGrid.types.ts

@@ -10,6 +10,56 @@ import type {
 } from "./index";
 import type { ConditionalFormat } from "./conditional-formatting";
 import type { MenuItem } from "./SvMenuList.svelte";
+import type { RecurrenceRule } from "./recurrence";
+
+/** The calendar views the scheduler can render. {@link SchedulerConfig}. The
+ *  `timeline*` views are horizontal: time runs left→right and resources are
+ *  rows (a single "All" row without `resourceField`). */
+export type SchedulerView =
+  | "month"
+  | "week"
+  | "day"
+  | "agenda"
+  | "timelineDay"
+  | "timelineWeek"
+  | "timelineMonth"
+  | "timelineYear";
+
+/**
+ * How overlapping ("colliding") time-grid events are laid out:
+ * - `split` - every collision divides the column width evenly (default).
+ * - `cap`   - show up to `maxColumns` columns; the rest collapse into a
+ *             clickable `+N more` overflow tile.
+ * - `stack` - overlapping events overlap with a horizontal offset + z-order
+ *             instead of shrinking, so each stays readable (hover to raise).
+ */
+export type SchedulerCollisionMode = "split" | "cap" | "stack";
+
+/** A scheduler resource - a person / room / machine an event can be assigned to. */
+export type SchedulerResource = {
+  id: string;
+  title?: string;
+  color?: string;
+  /**
+   * This resource's own working windows (hours), optionally per weekday - e.g. a
+   * doctor available Mon/Wed/Fri 9-13 and Tue/Thu 14-18. Overrides the global
+   * `businessHours` / `nonWorkingDays` for this resource's columns: time outside
+   * every matching window is shaded, and (with `restrictToBusinessHours`)
+   * non-bookable. A weekday with no matching window is a full day off.
+   */
+  availability?: ReadonlyArray<{ days?: ReadonlyArray<number>; start: number; end: number }>;
+  /**
+   * Per-date overrides to this resource's weekly `availability` - a specific day
+   * off (`off: true`, e.g. vacation) or custom hours (`windows`) for that one
+   * date. Matched by calendar date; takes precedence over `availability` for the
+   * matching day.
+   */
+  dateOverrides?: ReadonlyArray<{
+    date: Date | number | string;
+    off?: boolean;
+    windows?: ReadonlyArray<{ start: number; end: number }>;
+  }>;
+};
 import type {
   ChartType,
   ChartSpec,
@@ -450,6 +500,398 @@ export type BoardConfig<TFeatures extends TableFeatures = TableFeatures, TData e
   onLayoutChange?: (layout: BoardLayout) => void;
 };
 
+/**
+ * The built-in event detail drawer for the scheduler. Set `scheduler.drawer`
+ * (`true` for all fields, or this object) and clicking an event opens a drawer
+ * with an `SvForm` of its fields. Mirrors {@link BoardDrawerConfig}.
+ */
+export type SchedulerDrawerConfig<TData extends RowData = RowData> = {
+  /** Fields to show, in order. Omit for every column that has a `field`. */
+  fields?: ReadonlyArray<keyof TData & string>;
+  /** Drawer title - a string or derived from the row. Defaults to the title field. */
+  title?: string | ((row: TData) => string);
+  /** Which edge the drawer opens from. Defaults to `'right'`. */
+  side?: "right" | "left" | "top" | "bottom";
+  /** Drawer size (any CSS length). Defaults to `'380px'`. */
+  size?: string;
+  /** Save button label. Defaults to `'Save'`. */
+  submitLabel?: string;
+  /** Form columns inside the drawer. Defaults to `1`. */
+  columns?: number;
+};
+
+/** Emitted when an event is dragged to a new time (and/or resource). */
+export type SchedulerEventMoveEvent<TData extends RowData = RowData> = {
+  /** The dragged row. */
+  row: TData;
+  /** New start / end after the move. */
+  start: Date;
+  end: Date;
+  /** Whether the event is all-day after the move. */
+  allDay: boolean;
+  /** Resource it came from (only with `resourceField`). */
+  fromResource?: string;
+  /** Resource it was dropped on (only with `resourceField`). */
+  toResource?: string;
+};
+
+/** Emitted when an event's start or end edge is dragged to resize it. */
+export type SchedulerEventResizeEvent<TData extends RowData = RowData> = {
+  row: TData;
+  start: Date;
+  end: Date;
+};
+
+/**
+ * A drag-selected range (see `rangeSelectable`). `start`/`end` are a single
+ * CONTINUOUS datetime range - dragging across days makes it a longer span, not a
+ * per-day rectangle. `days` / `resourceIds` list the days / resources the range
+ * touched (for reference); `allDay` is true when the all-day row was dragged.
+ */
+export type SchedulerRangeSelection = {
+  start: Date;
+  end: Date;
+  allDay?: boolean;
+  /** Every day the range touched (one entry for a within-a-day drag). */
+  days: Date[];
+  /** Every resource the range touched (empty without `resourceField`). */
+  resourceIds: string[];
+};
+
+/** Emitted when an event's built-in editor/drawer is saved. */
+export type SchedulerEventCommitEvent<TData extends RowData = RowData> = {
+  row: TData;
+  /** Only the fields that changed, `{ field: newValue }`. */
+  changes: Record<string, unknown>;
+  /** The full set of edited field values. */
+  values: Record<string, unknown>;
+};
+
+/**
+ * One override of a single occurrence of a recurring event (stored in the row's
+ * `recurrenceExceptionsField`). `occurrenceStart` identifies the occurrence (its
+ * original start, like an iCal `RECURRENCE-ID`); `deleted` removes just that one,
+ * otherwise the given fields override it. Times are the same ISO / Date shape you
+ * store on the row.
+ */
+export type SchedulerException = {
+  occurrenceStart: string | number | Date;
+  deleted?: boolean;
+  start?: string | number | Date;
+  end?: string | number | Date;
+  title?: string;
+  allDay?: boolean;
+};
+
+/** How a change to a recurring event should apply. */
+export type SchedulerEditScope = "occurrence" | "following" | "series";
+
+/**
+ * Fired when a single occurrence of a recurring event is edited or deleted (the
+ * user chose "This event"). Append/merge `exception` into the row's
+ * `recurrenceExceptionsField`; for `deleted` it carries `{ deleted: true }`.
+ */
+export type SchedulerOccurrenceChangeEvent<TData extends RowData = RowData> = {
+  row: TData;
+  /** The occurrence's original start (its identity within the series). */
+  occurrenceStart: Date;
+  /** The override to store (already in real-instant time). */
+  exception: SchedulerException;
+  /**
+   * Which scope the user chose. `'occurrence'` (default): merge `exception` into
+   * the row. `'following'` ("this and all following"): split the series - stop
+   * the original series before `occurrenceStart` and start a NEW series at it
+   * carrying `exception`'s start/end/deleted. `'series'` never reaches here (it
+   * edits the base row directly). Handle `'following'` in your own data.
+   */
+  scope: SchedulerEditScope;
+};
+
+/**
+ * Turns the grid into a calendar / scheduler. Set `scheduler` and the grid
+ * renders its rows as events on a Month / Week / Day / Agenda calendar (bucketed
+ * by time, and optionally split into per-resource columns) instead of a table.
+ * Dragging an event fires {@link SchedulerConfig.onEventMove} where you reassign
+ * the start / end (and resource) on your own data. Like the Kanban board, it is
+ * a pure *view of the grid*: it renders the grid's filtered + sorted rows and
+ * writes back only through callbacks, never mutating your data.
+ */
+export type SchedulerConfig<
+  TFeatures extends TableFeatures = TableFeatures,
+  TData extends RowData = RowData,
+> = {
+  /** Field holding each event's start (`Date` | epoch-ms | ISO string). Required. */
+  startField: keyof TData & string;
+  /** Field holding the end. Omit to use `defaultDurationMin` from the start. */
+  endField?: keyof TData & string;
+  /** Boolean field marking an event as all-day (rendered in the all-day row). */
+  allDayField?: keyof TData & string;
+  /** Field for the event title. Defaults to the first column's field. */
+  titleField?: keyof TData & string;
+  /** Field holding a per-event accent color (any CSS color). Else `color`. */
+  colorField?: keyof TData & string;
+  /** Fallback accent color for every event. */
+  color?: string;
+  /**
+   * Field holding a SECONDARY accent color, rendered as a strip on the LEFT edge
+   * of the event - distinct from the main `colorField`. Lets an event encode two
+   * dimensions at once (e.g. main color = person, left strip = role).
+   */
+  secondaryColorField?: keyof TData & string;
+  /**
+   * Field holding a free/busy status that drives a distinct visual treatment
+   * (Outlook-style): `'busy'` (default solid), `'free'` (hollow / outline),
+   * `'tentative'` (hatched), `'oof'` / `'outOfOffice'` (distinct tint). Ties to
+   * iCal `STATUS`. Unrecognised values render as busy.
+   */
+  statusField?: keyof TData & string;
+  /**
+   * Field holding minutes-before-start for a reminder. When set (and the event
+   * is upcoming) the scheduler fires `onReminder` once as that lead time is
+   * crossed - pair it with a toast. Ties to iCal `VALARM`.
+   */
+  reminderField?: keyof TData & string;
+  /** Fired once when an event's reminder lead time is crossed (see `reminderField`). */
+  onReminder?: (row: TData, minutesUntil: number) => void;
+  /**
+   * Field holding a {@link RecurrenceRule} (or array) - the row renders as one
+   * event per matching day in view, keeping its time-of-day + duration.
+   */
+  recurrenceField?: keyof TData & string;
+  /**
+   * Field holding an array of {@link SchedulerException} - per-occurrence
+   * overrides of a recurring event (a moved / edited / deleted single instance).
+   * When set, editing a recurring occurrence offers "This event" vs "All events"
+   * and "This event" fires {@link onOccurrenceChange}.
+   */
+  recurrenceExceptionsField?: keyof TData & string;
+  /** Event length in minutes when a row has a start but no `endField`. Default 60. */
+  defaultDurationMin?: number;
+
+  /** Which views to offer in the toolbar. Default all four. */
+  views?: ReadonlyArray<SchedulerView>;
+  /** The view shown first. Default `'month'`. */
+  initialView?: SchedulerView;
+  /** The date the calendar opens on. Defaults to "today". */
+  initialDate?: Date | number | string;
+  /**
+   * Controlled anchor date - when this changes the calendar navigates to it (a
+   * mini date-picker or external "go to" can drive the view). Pair with
+   * {@link onNavigate} for two-way sync.
+   */
+  date?: Date | number | string;
+  /** Fired when the visible date changes (prev / next / today). */
+  onNavigate?: (date: Date) => void;
+  /** First day of the week, 0-6 (0 = Sunday). Default 0. */
+  weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+  /** Time-grid slot size in minutes (week / day snap granularity). Default 30. */
+  slotMinutes?: number;
+  /**
+   * Slot sizes (minutes) offered as a runtime picker in the Week / Day time-grid
+   * ruler, e.g. `[60, 30, 15, 5]`. When set, a size selector appears in the
+   * toolbar and the ruler subdivides accordingly; the active size starts at
+   * `slotMinutes`. Omit to hide the picker (the ruler still uses `slotMinutes`).
+   */
+  slotSizes?: ReadonlyArray<number>;
+  /** First / last hour shown in the time-grid band (0-24). Default 0..24. */
+  dayStartHour?: number;
+  dayEndHour?: number;
+
+  // --- booking rules: working hours, non-working days, conflicts -------------
+  /**
+   * Working-hours window (hours, e.g. `{ start: 9, end: 17 }`). Time outside it
+   * is shaded in the Week / Day time-grid. Visual only - see `disableConflicts`
+   * to enforce.
+   */
+  businessHours?: { start: number; end: number };
+  /** Weekday numbers (0 = Sun … 6 = Sat) shaded as non-working (e.g. `[0, 6]`). */
+  nonWorkingDays?: ReadonlyArray<number>;
+  /** Shade elapsed time on today's column (the past is "used up"). */
+  shadeUntilNow?: boolean;
+  /**
+   * Enforce the shaded time: reject a drag / resize / create that lands outside
+   * `businessHours` or on a `nonWorkingDays` day (snap back + flash). Without
+   * this the shading is a visual hint only.
+   */
+  restrictToBusinessHours?: boolean;
+  /**
+   * Prevent double-booking: dragging / resizing / creating an event so it
+   * overlaps another event **on the same resource** is rejected and reverted.
+   */
+  disableConflicts?: boolean;
+  /**
+   * Hard-blocked hour bands (e.g. a daily maintenance window `[{ start: 12, end: 13 }]`).
+   * Unlike `businessHours` these are ALWAYS non-bookable (drop / create rejected,
+   * no opt-in needed) and rendered as a distinct restricted (hatched) band.
+   */
+  restrictedHours?: ReadonlyArray<{ start: number; end: number }>;
+  /** Specific calendar dates that are fully blocked (no bookings) - e.g. closures. */
+  restrictedDates?: ReadonlyArray<Date | number | string>;
+  /**
+   * Highlighted dates (holidays, launches …) - a coloured strip + optional label
+   * on that day's column / month cell. Decorative; does not block booking.
+   */
+  specialDates?: ReadonlyArray<{ date: Date | number | string; label?: string; color?: string }>;
+  /** Earliest navigable / bookable date. Prev-nav stops here and creates are blocked before it. */
+  minDate?: Date | number | string;
+  /** Latest navigable / bookable date. Next-nav stops here and creates are blocked after it. */
+  maxDate?: Date | number | string;
+  /**
+   * Cap concurrent events per resource at any moment: a drag / resize / create
+   * that would make more than N events overlap on the same resource is rejected.
+   */
+  maxEventsPerSlot?: number;
+  /**
+   * Enable **undo / redo** of drag-move + resize with `Ctrl/Cmd+Z` and
+   * `Ctrl/Cmd+Shift+Z` (or `Ctrl+Y`). The scheduler re-emits the move/resize
+   * callbacks with the reversed values, so your data follows.
+   */
+  history?: boolean;
+  /**
+   * Show the current-time indicator - a line across today's column(s) in the
+   * Week / Day time-grid and the Day timeline, tracking the local time. On by
+   * default; set to `false` to hide it.
+   */
+  nowIndicator?: boolean;
+  /**
+   * IANA time zone (e.g. `'America/New_York'`) the whole calendar is shown in -
+   * the hour ruler, event positions, day boundaries, all-day grouping and the
+   * now-line. Defaults to the browser's local zone. Event `start`/`end` must be
+   * instant-unambiguous (UTC / offset ISO or epoch ms) for this to be correct;
+   * bare local strings are read as wall-clock in this zone.
+   */
+  timeZone?: string;
+  /**
+   * Extra read-only hour rulers for other zones (a "world clock"), shown left of
+   * the primary ruler in the Week / Day time-grid. Each entry's `label` heads its
+   * column (defaults to a short zone abbreviation).
+   */
+  secondaryTimeZones?: ReadonlyArray<{ id: string; label?: string }>;
+  /**
+   * How overlapping time-grid events are laid out. `split` (default) divides the
+   * width evenly per collision; `cap` shows up to `maxColumns` then a clickable
+   * `+N more` tile; `stack` overlaps them with an offset instead of shrinking.
+   */
+  collisionMode?: SchedulerCollisionMode;
+  /** For `collisionMode: 'cap'`: max side-by-side columns before overflow (min 2). Default 3. */
+  maxColumns?: number;
+  /** How many days the agenda view spans. Default 30. */
+  agendaDays?: number;
+
+  /**
+   * Field whose value groups events by resource (people, rooms, machines). In
+   * the Week / Day time-grid the columns split into resource x day groups; a
+   * resource filter/legend appears in every view. See {@link SchedulerResource}.
+   */
+  resourceField?: keyof TData & string;
+  /** Explicit, ordered resources (with colors). Omit to derive from the data. */
+  resources?: ReadonlyArray<SchedulerResource>;
+  /**
+   * Time-grid resource grouping order. `false` (default) groups by resource then
+   * day (resource-major); `true` groups by day then resource (date-major), like
+   * Smart's `groupByDate`. Only affects Week / Day when `resourceField` is set.
+   */
+  groupByDate?: boolean;
+
+  /** Timeline views only: width (px) of the left resource-label gutter. Default 160. */
+  resourceAreaWidth?: number;
+  /** `timelineDay` tick size + move/resize snap, in minutes. Default = `slotMinutes`. */
+  timelineSlotMinutes?: number;
+  /** Timeline views only: height (px) of one event lane inside a resource row. Default 26. */
+  timelineLaneHeight?: number;
+
+  /** Enable drag-to-move and edge-resize. Without it the calendar is read-only. */
+  editable?: boolean;
+  /** Fired when an event is dragged to a new time / resource. */
+  onEventMove?: (event: SchedulerEventMoveEvent<TData>) => void;
+  /** Fired when an event edge is dragged to resize it. */
+  onEventResize?: (event: SchedulerEventResizeEvent<TData>) => void;
+  /**
+   * Fired to create an event - double-clicking an empty slot, or confirming a
+   * pending range when no {@link onRangeSelect} is set. `allDay` is `true` when
+   * the slot / range is an all-day one (the all-day row, a month day cell, or a
+   * multi-day timeline zoom), so the handler can set the `allDayField`.
+   */
+  onEventAdd?: (start: Date, end: Date, resourceId?: string, allDay?: boolean) => void;
+  /**
+   * Fired when the event's Delete button is used. Setting this shows a Delete
+   * button in the detail drawer (and a `Delete` item is easy to add via
+   * `eventMenu`). Remove the row from your data in the handler.
+   */
+  onEventDelete?: (row: TData) => void;
+  /**
+   * Fired when a single occurrence of a recurring event is moved / resized /
+   * deleted with scope "This event". Merge `event.exception` into the row's
+   * `recurrenceExceptionsField` array (keyed by `occurrenceStart`).
+   */
+  onOccurrenceChange?: (event: SchedulerOccurrenceChangeEvent<TData>) => void;
+
+  /**
+   * Selecting empty cells: click or drag across the time-grid / timeline to mark
+   * a time range (and, across days / resources, a rectangle of cells). Arrow keys
+   * move the selection and `Shift`+arrows extend it. Marking only *marks* the
+   * range - it does NOT create anything. The event is created on an explicit
+   * confirm: press `Enter`, or right-click the selection and choose "Add Event".
+   * Confirming fires {@link onRangeSelect}, or falls back to `onEventAdd` for the
+   * first cell; `Escape` cancels the marker.
+   *
+   * On by default; set to `false` to disable.
+   */
+  rangeSelectable?: boolean;
+  /**
+   * Fired when a pending cell range is confirmed with `Enter` or the "Add Event"
+   * context menu (see {@link rangeSelectable}) - not on drag release.
+   */
+  onRangeSelect?: (selection: SchedulerRangeSelection) => void;
+  /**
+   * Multi-selecting existing events: Ctrl/Cmd-click toggles, Shift-click
+   * range-selects; a plain click clears. Selected events move together when one
+   * is dragged, and `Delete` removes them (via `onEventDelete`).
+   *
+   * On by default; set to `false` to disable.
+   */
+  eventSelectable?: boolean;
+  /** Fired when the set of multi-selected events changes. */
+  onEventSelectionChange?: (rows: TData[]) => void;
+
+  /**
+   * An "unscheduled" backlog list shown beside the Week / Day grid: drag an item
+   * onto the calendar to schedule it. Each item is `{ id, title, durationMin?,
+   * color? }`. Dropping fires {@link onSchedule} with the drop time + resource.
+   */
+  unscheduled?: ReadonlyArray<{ id: string; title: string; durationMin?: number; color?: string }>;
+  /** Optional heading for the unscheduled backlog panel. Default "Unscheduled". */
+  backlogTitle?: string;
+  /** Fired when an unscheduled item is dropped on the grid - create an event from it. */
+  onSchedule?: (item: { id: string; title: string; durationMin?: number; color?: string }, start: Date, resourceId?: string) => void;
+  /**
+   * Fired when an event is dragged OFF the calendar onto the backlog panel -
+   * remove it from the schedule (and typically push it back to `unscheduled`).
+   * Requires the backlog panel (an `unscheduled` list) to be visible.
+   */
+  onUnschedule?: (row: TData) => void;
+
+  /** Custom event body. Receives the row. Omit for the built-in default (title). */
+  event?: Snippet<[TData]>;
+  /**
+   * Hover tooltip for an event. Set a `Snippet<[TData]>` for custom content, or
+   * `true` for the built-in tooltip (title + time + resource). Omit to disable.
+   */
+  tooltip?: boolean | Snippet<[TData]>;
+  /** Delay (ms) before the hover tooltip opens. Default 400. */
+  tooltipDelay?: number;
+  /** Built-in detail drawer: `true` for all fields, or a config object. */
+  drawer?: boolean | SchedulerDrawerConfig<TData>;
+  /** Fired when the drawer / editor is saved. */
+  onEventCommit?: (event: SchedulerEventCommitEvent<TData>) => void;
+  /** Right-click menu for an event. Return items or `undefined` to suppress. */
+  eventMenu?: (row: TData) => MenuItem[] | undefined;
+
+  /** Show the search box (binds to the grid's global filter). Default `true`. */
+  searchable?: boolean;
+  searchPlaceholder?: string;
+};
+
 export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends RowData = RowData> = {
   data: ReadonlyArray<TData>;
   columns: Array<ColumnDef<TFeatures, TData>>;
@@ -459,6 +901,12 @@ export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends
    * {@link BoardConfig}.
    */
   board?: BoardConfig<TFeatures, TData>;
+  /**
+   * Scheduler / calendar mode. When set, the grid renders its rows as events on
+   * a Month / Week / Day / Agenda calendar instead of a table. See
+   * {@link SchedulerConfig}.
+   */
+  scheduler?: SchedulerConfig<TFeatures, TData>;
   /**
    * Right-click context menu. `true` shows the default item set (copy, cut,
    * paste, clear, insert row above/below, remove row, remove column). Pass an
@@ -808,6 +1256,13 @@ export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends
    * or omit it to apply to every column. Later entries win on conflict.
    */
   conditionalFormats?: ReadonlyArray<ConditionalFormat<TData>>;
+  /**
+   * Which rows feed the min/max range that `colorScale` / `dataBar` formats
+   * scale against. `visible` (default): the currently displayed rows (after
+   * filtering + paging), so the heat map adapts to what's on screen. `all`:
+   * the full unfiltered dataset, for a scale that stays put as you filter.
+   */
+  conditionalStatScope?: "visible" | "all";
   onCellValueChange?: (event: {
     rowIndex: number;
     columnId: string;
@@ -1013,12 +1468,19 @@ export type CellEditState = {
 } | null;
 export type FilterOperator =
   | "contains"
+  | "notContains"
   | "equals"
+  | "notEquals"
   | "startsWith"
+  | "endsWith"
+  | "regex"
+  | "in"
+  | "notIn"
   | "greaterThan"
   | "lessThan"
   | "between"
-  | "isBlank";
+  | "isBlank"
+  | "isNotBlank";
 export type FilterOption = {
   value: FilterOperator;
   label: string;

package/src/SvGridDropdown.svelte

@@ -88,6 +88,8 @@
     left: 0,
     width: 0,
     openUpward: false,
+    maxHeight: 0,
+    availHeight: 0,
   })
 
   const selectedArr = $derived(
@@ -376,7 +378,12 @@
          Panel is `position: fixed` + portal'd to <body> so it escapes
          the grid's overflow:hidden scroll container. -->
     {@const needsScroll = options.length > 10}
-    {@const panelMax = needsScroll ? 10 * 32 + (multiple ? 40 : 0) + 8 : null}
+    <!-- Cap to the comfortable 10-row height AND the room the viewport allows,
+         so a panel near the bottom edge scrolls instead of overflowing. -->
+    {@const panelMax = Math.min(
+      needsScroll ? 10 * 32 + (multiple ? 40 : 0) + 8 : Number.POSITIVE_INFINITY,
+      panelRect.maxHeight,
+    )}
     <div
       class="sv-grid-dropdown-panel"
       class:sv-grid-dropdown-panel-fits={!needsScroll}

package/src/SvGridSelect.svelte

@@ -153,6 +153,7 @@
     style:top={`${gs.rect.top}px`}
     style:left={`${gs.rect.left}px`}
     style:min-width={`${Math.max(gs.rect.width, 320)}px`}
+    style:max-height={`${gs.rect.maxHeight}px`}
     onkeydown={gs.onPanelKeydown}
   >
     {#if searchable}

package/src/SvListBox.svelte

@@ -5,7 +5,7 @@
    * via `value` (scalar or array) + `onChange`. Scales to huge option sets with
    * `virtual` (fixed-row windowing), and each row can be an `itemTemplate`.
    */
-  import { flushSync, type Snippet } from 'svelte'
+  import { type Snippet } from 'svelte'
   import { groupOptions, hasGroups, type ListOption } from './list-option'
   import { virtualRange, scrollToIndex } from './virtual'
   import { createListbox } from './createListbox.svelte'
@@ -101,17 +101,25 @@
     class:is-invalid={invalid}
     class:is-virtual={useVirtual}
     style:--sv-rows={rows}
-    onscroll={(e) => { scrollTop = e.currentTarget.scrollTop; if (useVirtual) flushSync() }}
+    style:--sv-row-h={`${rowHeight}px`}
+    onscroll={(e) => (scrollTop = e.currentTarget.scrollTop)}
     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>
+      <!-- Windowing by top/bottom spacers with the visible rows IN FLOW between
+           them (padTop + rows + padBottom always sum to the full height). Plain
+           flow rows (no absolute positioning, no will-change) keep the scroller
+           off its own compositor layer, so a fast jump repaints in step with the
+           scroll instead of showing the blank frame a promoted layer would. The
+           window updates from `scrollTop` state, which Svelte flushes before the
+           next paint - no flushSync (it over-flushes app-wide and, on a fling,
+           starves the very handler that has to keep up with the scroll). -->
+      <li class="sv-listbox__spacer" aria-hidden="true" style:height={`${vr.padTop}px`}></li>
       {#each windowed as opt (opt.value)}
         {@render optionLi(opt, opt.index)}
       {/each}
+      <li class="sv-listbox__spacer" aria-hidden="true" style:height={`${vr.padBottom}px`}></li>
     {:else}
       {#each groupOptions(options) as g (g.group ?? ' ')}
         {#if g.group != null}<li class="sv-listbox__group" role="presentation">{g.group}</li>{/if}
@@ -132,7 +140,6 @@
     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}
@@ -144,7 +151,7 @@
   .sv-listbox {
     --_accent: var(--sg-accent, #2563eb);
     margin: 0; padding: 4px; list-style: none;
-    max-height: calc(var(--sv-rows, 7) * 32px + 8px); overflow-y: auto;
+    max-height: calc(var(--sv-rows, 7) * var(--sv-row-h, 32px) + 8px); overflow-y: auto;
     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);
     width: 220px; outline: none;
@@ -152,15 +159,30 @@
   .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;
+  /* Spacers reserve the off-screen height above/below the windowed rows. They
+     also paint faint per-row skeleton bars: on a fast scrollbar-thumb drag the
+     compositor can reveal this padding before JS re-windows (a drag jumps many
+     rows in one frame - overscan can't cover it), so the user would see blank.
+     The skeleton fills that gap with placeholder rows that the real rows paint
+     over a frame later. Bars are one per `--sv-row-h` band, aligned to the row
+     grid (padTop/padBottom are exact multiples of the row height). */
+  .sv-listbox__spacer {
+    padding: 0; margin: 0; flex: none; pointer-events: none; list-style: none;
+    background-image: linear-gradient(
+      to bottom,
+      transparent 0,
+      transparent calc((var(--sv-row-h, 32px) - 10px) / 2),
+      var(--sg-skeleton, color-mix(in srgb, currentColor 9%, transparent)) calc((var(--sv-row-h, 32px) - 10px) / 2),
+      var(--sg-skeleton, color-mix(in srgb, currentColor 9%, transparent)) calc((var(--sv-row-h, 32px) + 10px) / 2),
+      transparent calc((var(--sv-row-h, 32px) + 10px) / 2),
+      transparent var(--sv-row-h, 32px)
+    );
+    background-size: 62% var(--sv-row-h, 32px);
+    background-repeat: repeat-y;
+    background-position: 12px 0;
   }
   .sv-listbox__opt {
-    display: flex; align-items: center; gap: 8px; box-sizing: border-box; padding: 0 10px;
+    display: flex; align-items: center; gap: 8px; box-sizing: border-box; flex: none; padding: 0 10px;
     border-radius: 6px; cursor: pointer; font-size: 13px;
   }
   .sv-listbox__opt.is-active { background: var(--sg-row-hover-bg, #f1f5f9); }

package/src/SvMaskedInput.svelte

@@ -27,7 +27,7 @@
   }
 
   let {
-    value = '',
+    value = $bindable(''),
     onChange,
     mask = '',
     placeholder,
@@ -53,7 +53,8 @@
 
   const mi = createMaskedInput({
     value: () => value,
-    onChange: (m, r, c) => onChange?.(m, r, c),
+    // Write the masked `value` (so `bind:value` works) AND fire `onChange`.
+    onChange: (m, r, c) => { value = m; onChange?.(m, r, c) },
     mask: () => mask,
     placeholder: () => placeholder,
     disabled: () => disabled,
@@ -72,7 +73,7 @@
     {#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)}>
+      <button type="button" class="sv-masked__clear" aria-label="Clear" tabindex="-1" onclick={() => { value = ''; 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}

package/src/SvMenu.svelte

@@ -45,7 +45,7 @@
 
   let anchorEl = $state<HTMLSpanElement | null>(null)
   let panelEl = $state<HTMLDivElement | null>(null)
-  let rect = $state<AnchoredRect>({ top: 0, left: 0, width: 0, openUpward: false })
+  let rect = $state<AnchoredRect>({ top: 0, left: 0, width: 0, openUpward: false, maxHeight: 0, availHeight: 0 })
 
   function setOpen(v: boolean) { if (v !== open) { open = v; onOpenChange?.(v) } }
   function toggle() { setOpen(!open) }