@svgrid/grid 2.1.21 → 2.1.23

package/dist/SvGrid.types.d.ts

@@ -2,6 +2,51 @@ import type { Snippet } from "svelte";
 import type { CellEditorType, ColumnDef, RowData, SvGridApi, TableFeatures } from "./index";
 import type { ConditionalFormat } from "./conditional-formatting";
 import type { MenuItem } from "./SvMenuList.svelte";
+/** 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, ChartAnnotation, ChartReferenceLine } from "./chart";
 /** One aggregated bucket returned by a server-side `getAggregate`. */
 export type ChartAggregateBucket = {
@@ -422,6 +467,399 @@ export type BoardConfig<TFeatures extends TableFeatures = TableFeatures, TData e
     /** Called whenever the board layout changes, with the serializable state. */
     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;
+    /**
+     * 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>>;
@@ -431,6 +869,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
@@ -783,6 +1227,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;
@@ -991,7 +1442,7 @@ export type CellEditState = {
     editorType: CellEditorType;
     value: unknown;
 } | null;
-export type FilterOperator = "contains" | "equals" | "startsWith" | "greaterThan" | "lessThan" | "between" | "isBlank";
+export type FilterOperator = "contains" | "notContains" | "equals" | "notEquals" | "startsWith" | "endsWith" | "regex" | "in" | "notIn" | "greaterThan" | "lessThan" | "between" | "isBlank" | "isNotBlank";
 export type FilterOption = {
     value: FilterOperator;
     label: string;

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

@@ -20,6 +20,6 @@ type Props = SvEditorProps & {
     prefixIcon?: Snippet;
     suffixIcon?: Snippet;
 };
-declare const SvMaskedInput: import("svelte").Component<Props, {}, "">;
+declare const SvMaskedInput: import("svelte").Component<Props, {}, "value">;
 type SvMaskedInput = ReturnType<typeof SvMaskedInput>;
 export default SvMaskedInput;

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