@svgrid/grid 2.1.22 → 2.2.0

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;