@svgrid/grid 2.1.22 → 2.2.0

package/src/recurrence.ts

@@ -1,15 +1,19 @@
 /**
  * recurrence - a small, pure repeat-pattern engine for SvCalendar (and anywhere
  * you need "does this date match a recurring rule"). Supports daily / weekly /
- * monthly / yearly frequencies with an interval, weekday lists, a day-of-month,
- * an anchor (`from`) and an inclusive `until`. Framework-free + pure so it is
- * unit-tested directly - no RRULE dependency.
+ * monthly / yearly frequencies with an interval, weekday lists, a day-of-month
+ * (incl. negative = counted from the end), a positional weekday-of-month
+ * (`weekOfMonth`, e.g. the 2nd Tuesday / last Friday), an anchor (`from`) and two
+ * end conditions - an inclusive `until` date or a `count` of occurrences.
+ * Framework-free + pure so it is unit-tested directly - no RRULE dependency.
  *
  * ```ts
  * const standup = { freq: 'weekly', weekdays: [1, 2, 3, 4, 5] } // every weekday
- * const payday  = { freq: 'monthly', day: 1 }                   // the 1st
+ * const payday  = { freq: 'monthly', day: -1 }                  // the last day
  * const sprint  = { freq: 'weekly', weekdays: [1], interval: 2, from: '2026-01-05' } // every other Monday
- * matchesRecurrence(someDate, [standup, payday, sprint])
+ * const board   = { freq: 'monthly', weekdays: [2], weekOfMonth: 1 } // 1st Tuesday
+ * const review  = { freq: 'weekly', weekdays: [5], count: 8 }   // 8 Fridays then stop
+ * matchesRecurrence(someDate, [standup, payday, sprint, board, review])
  * ```
  */
 import { startOfDay, startOfWeek, toDate, type DateLike } from './datetime/date-core'
@@ -20,23 +24,42 @@ export type RecurrenceRule = {
   freq: RecurrenceFreq
   /** Repeat every N units of `freq`. Default 1. Uses `from` as the phase anchor. */
   interval?: number
-  /** weekly: the weekdays it lands on (0 = Sunday .. 6 = Saturday). */
+  /** weekly: the weekdays it lands on (0 = Sunday .. 6 = Saturday). Also the
+   *  weekday for a positional monthly / yearly rule (with `weekOfMonth`). */
   weekdays?: ReadonlyArray<number>
-  /** monthly / yearly: day of the month (1..31). */
+  /** monthly / yearly: day of the month. 1..31, or negative to count from the
+   *  end (-1 = the last day, -2 = the second to last). */
   day?: number
+  /** monthly / yearly: the ordinal week the `weekdays` land on within the month -
+   *  1..4 (first..fourth) or -1 (last). E.g. `{ weekdays:[2], weekOfMonth:-1 }`
+   *  = the last Tuesday. Takes precedence over `day` when both are set. */
+  weekOfMonth?: number
   /** yearly: the month (0 = January .. 11 = December). */
   month?: number
   /** First occurrence + the phase for `interval`. */
   from?: DateLike
   /** Last day the pattern applies (inclusive). */
   until?: DateLike | null
+  /** End after this many occurrences (counted from `from`). Requires `from`. */
+  count?: number
 }
 
 const MS_DAY = 86_400_000
 /** Whole-day index, rounded so DST transitions don't shift it. */
 const dayIndex = (d: Date) => Math.round(startOfDay(d).getTime() / MS_DAY)
+/** Days in the month that `d` falls in. */
+const daysInMonth = (d: Date) => new Date(d.getFullYear(), d.getMonth() + 1, 0).getDate()
+/** Whether `d` is the `nth` occurrence of its own weekday within its month -
+ *  nth 1..4 (first..fourth) or -1 (last). */
+function isNthWeekdayOfMonth(d: Date, nth: number): boolean {
+  if (nth === -1) return d.getDate() + 7 > daysInMonth(d) // no same weekday later this month
+  return Math.floor((d.getDate() - 1) / 7) + 1 === nth
+}
 
-function matchesRule(date: Date, r: RecurrenceRule): boolean {
+function matchesRule(date: Date, rule: RecurrenceRule): boolean {
+  // Fold a `count` end-condition into an equivalent `until` first (pure), so the
+  // rest of the matcher stays a stateless per-date test.
+  const r = rule.count && rule.count >= 1 && rule.from != null ? resolveCount(rule) : rule
   const d = startOfDay(date)
   const fromD = r.from != null ? startOfDay(toDate(r.from) ?? d) : null
   const untilD = r.until != null ? startOfDay(toDate(r.until) ?? d) : null
@@ -64,23 +87,59 @@ function matchesRule(date: Date, r: RecurrenceRule): boolean {
     }
 
     case 'monthly': {
-      const dom = r.day ?? fromD?.getDate()
-      if (dom != null && d.getDate() !== dom) return false
-      if (!fromD) return dom != null
+      if (!matchesMonthDay(d, r)) return false
+      if (!fromD) return true
       const months = (d.getFullYear() - fromD.getFullYear()) * 12 + (d.getMonth() - fromD.getMonth())
       return months % interval === 0
     }
 
     case 'yearly': {
       if (r.month != null && d.getMonth() !== r.month) return false
-      const dom = r.day ?? fromD?.getDate()
-      if (dom != null && d.getDate() !== dom) return false
-      if (!fromD) return r.month != null || dom != null
+      if (!matchesMonthDay(d, r)) return false
+      if (!fromD) return r.month != null || r.day != null || r.weekOfMonth != null
       return (d.getFullYear() - fromD.getFullYear()) % interval === 0
     }
   }
 }
 
+// The day-within-the-month test shared by monthly + yearly: a positional
+// weekday (`weekOfMonth` + `weekdays`), else a day-of-month (`day`, negative =
+// from the end), else - for a `from`-anchored rule - the anchor's day-of-month.
+function matchesMonthDay(d: Date, r: RecurrenceRule): boolean {
+  if (r.weekOfMonth != null && r.weekdays && r.weekdays.length) {
+    return r.weekdays.includes(d.getDay()) && isNthWeekdayOfMonth(d, r.weekOfMonth)
+  }
+  const fromDom = r.from != null ? (toDate(r.from) ?? d).getDate() : null
+  const dom = r.day ?? fromDom
+  if (dom == null) return false
+  const target = dom < 0 ? daysInMonth(d) + dom + 1 : dom
+  return d.getDate() === target
+}
+
+/** Fold a `count` rule into an equivalent `until`-bounded rule by walking
+ *  forward from `from` to the Nth occurrence. Pure; count is then stripped. */
+function resolveCount(rule: RecurrenceRule): RecurrenceRule {
+  const from = toDate(rule.from!)
+  if (!from) return { ...rule, count: undefined }
+  const base: RecurrenceRule = { ...rule, count: undefined }
+  let cur = startOfDay(from)
+  let n = 0
+  let lastMatch = cur
+  let guard = 0
+  while (guard++ < 4000 * 12) {
+    if (matchesRule(cur, base)) {
+      n++
+      lastMatch = cur
+      if (n >= rule.count!) break
+    }
+    cur = new Date(cur.getFullYear(), cur.getMonth(), cur.getDate() + 1)
+  }
+  const untilFromCount = lastMatch
+  const existingUntil = rule.until != null ? startOfDay(toDate(rule.until) ?? untilFromCount) : null
+  const until = existingUntil && existingUntil < untilFromCount ? existingUntil : untilFromCount
+  return { ...base, until }
+}
+
 /** Whether `date` matches any of the given recurrence rule(s). */
 export function matchesRecurrence(
   date: Date,
@@ -99,13 +158,105 @@ export function expandRecurrence(
   end: Date,
 ): Date[] {
   if (!rules) return []
+  // Pre-resolve any `count` end-condition into a plain `until` once (rather than
+  // re-walking to the Nth occurrence for every day in the window).
+  const list = (Array.isArray(rules) ? rules : [rules]).map((r) =>
+    r.count && r.count >= 1 && r.from != null ? resolveCount(r) : r,
+  )
   const out: Date[] = []
   const last = startOfDay(end)
   let cur = startOfDay(start)
   let guard = 0
   while (cur <= last && guard++ < 4000) {
-    if (matchesRecurrence(cur, rules)) out.push(cur)
+    if (matchesRecurrence(cur, list)) out.push(cur)
     cur = new Date(cur.getFullYear(), cur.getMonth(), cur.getDate() + 1)
   }
   return out
 }
+
+// --- human-readable summaries (for a table cell, a chip, a tooltip) ----------
+
+/** Optional English strings a caller can override for i18n. */
+export type RecurrenceLabels = {
+  weekdays?: ReadonlyArray<string> // Sun..Sat
+  months?: ReadonlyArray<string> // Jan..Dec
+  ordinals?: Record<number, string> // 1..5 + -1
+  never?: string
+}
+const WD = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat']
+const MO = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']
+const ORD: Record<number, string> = { 1: 'first', 2: 'second', 3: 'third', 4: 'fourth', 5: 'fifth', [-1]: 'last' }
+
+// Where in the month a monthly / yearly rule lands, as a phrase.
+function whereInMonth(r: RecurrenceRule, wd: ReadonlyArray<string>, ord: Record<number, string>): string {
+  if (r.weekOfMonth != null && r.weekdays && r.weekdays.length) {
+    return `the ${ord[r.weekOfMonth] ?? r.weekOfMonth} ${wd[r.weekdays[0]]}`
+  }
+  if (r.day === -1) return 'the last day'
+  if (r.day != null && r.day < 0) return `the ${-r.day} day(s) from the end`
+  if (r.day != null) return `day ${r.day}`
+  return ''
+}
+
+function describeRule(r: RecurrenceRule, L: Required<RecurrenceLabels>): string {
+  const n = Math.max(1, Math.floor(r.interval ?? 1))
+  let s = ''
+  switch (r.freq) {
+    case 'daily':
+      s = n === 1 ? 'Daily' : `Every ${n} days`
+      break
+    case 'weekly': {
+      s = n === 1 ? 'Weekly' : `Every ${n} weeks`
+      const wds = r.weekdays && r.weekdays.length ? [...r.weekdays].sort((a, b) => a - b) : []
+      if (wds.length) {
+        const isWeekdays = wds.length === 5 && [1, 2, 3, 4, 5].every((d) => wds.includes(d))
+        const isWeekend = wds.length === 2 && wds.includes(0) && wds.includes(6)
+        s += isWeekdays ? ' on weekdays' : isWeekend ? ' on weekends' : ` on ${wds.map((d) => L.weekdays[d]).join(', ')}`
+      }
+      break
+    }
+    case 'monthly': {
+      s = n === 1 ? 'Monthly' : `Every ${n} months`
+      const where = whereInMonth(r, L.weekdays, L.ordinals)
+      if (where) s += ` on ${where}`
+      break
+    }
+    case 'yearly': {
+      s = n === 1 ? 'Yearly' : `Every ${n} years`
+      const where = whereInMonth(r, L.weekdays, L.ordinals)
+      if (r.month != null && where) s += ` on ${where} of ${L.months[r.month]}`
+      else if (r.month != null) s += ` in ${L.months[r.month]}`
+      else if (where) s += ` on ${where}`
+      break
+    }
+  }
+  // End condition.
+  if (r.count && r.count >= 1) s += `, ${r.count} time${r.count === 1 ? '' : 's'}`
+  else if (r.until) {
+    const u = toDate(r.until)
+    if (u) s += ` until ${L.months[u.getMonth()]} ${u.getDate()}, ${u.getFullYear()}`
+  }
+  return s
+}
+
+/**
+ * A short, human-readable summary of a recurrence rule (or list) - e.g.
+ * "Weekly on weekdays", "Every 2 weeks on Fri, 8 times", "Monthly on the last
+ * Friday", "Yearly on the fourth Thursday of Nov". Returns the `never` label
+ * (default "") for an empty / falsy rule, so it drops cleanly into a table cell.
+ */
+export function describeRecurrence(
+  rules: RecurrenceRule | ReadonlyArray<RecurrenceRule> | null | undefined,
+  labels?: RecurrenceLabels,
+): string {
+  const L: Required<RecurrenceLabels> = {
+    weekdays: labels?.weekdays ?? WD,
+    months: labels?.months ?? MO,
+    ordinals: labels?.ordinals ?? ORD,
+    never: labels?.never ?? '',
+  }
+  if (!rules) return L.never
+  const list = (Array.isArray(rules) ? rules : [rules]).filter((r) => r && r.freq)
+  if (!list.length) return L.never
+  return list.map((r) => describeRule(r, L)).join('; ')
+}

package/src/render-component.ts

@@ -1,28 +1,28 @@
-import type { Component, ComponentProps, Snippet } from 'svelte'
-
-export class RenderComponentConfig<TComponent extends Component> {
-  constructor(
-    public component: TComponent,
-    public props?: ComponentProps<TComponent> | Record<string, never>,
-  ) {}
-}
-
-export class RenderSnippetConfig<TProps> {
-  constructor(
-    public snippet: Snippet<[TProps]>,
-    public params?: TProps,
-  ) {}
-}
-
-export const renderComponent = <
-  TComponent extends Component<any>,
-  TProps extends ComponentProps<TComponent>,
->(
-  component: TComponent,
-  props?: TProps,
-) => new RenderComponentConfig(component, props)
-
-export const renderSnippet = <TProps>(
-  snippet: Snippet<[TProps]>,
-  params?: TProps,
-) => new RenderSnippetConfig(snippet, params)
+import type { Component, ComponentProps, Snippet } from 'svelte'
+
+export class RenderComponentConfig<TComponent extends Component> {
+  constructor(
+    public component: TComponent,
+    public props?: ComponentProps<TComponent> | Record<string, never>,
+  ) {}
+}
+
+export class RenderSnippetConfig<TProps> {
+  constructor(
+    public snippet: Snippet<[TProps]>,
+    public params?: TProps,
+  ) {}
+}
+
+export const renderComponent = <
+  TComponent extends Component<any>,
+  TProps extends ComponentProps<TComponent>,
+>(
+  component: TComponent,
+  props?: TProps,
+) => new RenderComponentConfig(component, props)
+
+export const renderSnippet = <TProps>(
+  snippet: Snippet<[TProps]>,
+  params?: TProps,
+) => new RenderSnippetConfig(snippet, params)

package/src/row-drag.ts

@@ -178,6 +178,16 @@ export function createRowDrag<TFeatures, TData>(ctx: any) {
     onRowsContainerDrop,
     onRowDragEnd,
     rowDragGridId: gridId,
+    /**
+     * Clear any managed drag this grid currently owns. Call on unmount so an
+     * interrupted drag (route change / `{#if}` toggle mid-drag) doesn't leave a
+     * stale module-level `bus` that fires `removeFromSource` against a destroyed
+     * grid's data on the next grid instance (#68). Guarded by `gridId` so it
+     * never disturbs a concurrent drag owned by another grid.
+     */
+    destroyRowDrag() {
+      if (bus?.gridId === gridId) bus = null;
+    },
   };
 }
 

package/src/scheduler-ical.test.ts

@@ -0,0 +1,68 @@
+import { describe, it, expect } from 'vitest'
+import { toICS, fromICS, ruleToRRule, rruleToRule, type ICalEvent } from './scheduler-ical'
+import type { RecurrenceRule } from './recurrence'
+
+describe('iCal RRULE round-trip', () => {
+  const cases: [RecurrenceRule, string][] = [
+    [{ freq: 'weekly', weekdays: [1, 3, 5] }, 'FREQ=WEEKLY;BYDAY=MO,WE,FR'],
+    [{ freq: 'daily', interval: 2 }, 'FREQ=DAILY;INTERVAL=2'],
+    [{ freq: 'monthly', day: -1 }, 'FREQ=MONTHLY;BYMONTHDAY=-1'],
+    [{ freq: 'monthly', weekdays: [2], weekOfMonth: 1 }, 'FREQ=MONTHLY;BYDAY=1TU'],
+    [{ freq: 'monthly', weekdays: [5], weekOfMonth: -1 }, 'FREQ=MONTHLY;BYDAY=-1FR'],
+    [{ freq: 'yearly', month: 10, weekdays: [4], weekOfMonth: 4 }, 'FREQ=YEARLY;BYDAY=4TH;BYMONTH=11'],
+    [{ freq: 'weekly', weekdays: [1], count: 8 }, 'FREQ=WEEKLY;BYDAY=MO;COUNT=8'],
+  ]
+  it('serializes rules to RRULE', () => {
+    for (const [rule, str] of cases) expect(ruleToRRule(rule)).toBe(str)
+  })
+  it('parses RRULE back to an equivalent rule', () => {
+    for (const [rule, str] of cases) expect(rruleToRule(str)).toMatchObject(rule)
+  })
+})
+
+describe('toICS / fromICS', () => {
+  const events: ICalEvent[] = [
+    { uid: 'a@x', title: 'Kickoff, prep', start: new Date('2026-07-06T09:00:00Z'), end: new Date('2026-07-06T10:00:00Z'), status: 'confirmed' },
+    { uid: 'b@x', title: 'Offsite', start: new Date('2026-07-08T00:00:00Z'), end: new Date('2026-07-10T00:00:00Z'), allDay: true },
+    { uid: 'c@x', title: 'Standup', start: new Date('2026-07-06T09:30:00Z'), end: new Date('2026-07-06T09:45:00Z'), rrule: { freq: 'weekly', weekdays: [1, 2, 3, 4, 5] } },
+  ]
+
+  it('produces a valid VCALENDAR with one VEVENT per event', () => {
+    const ics = toICS(events)
+    expect(ics).toMatch(/^BEGIN:VCALENDAR/)
+    expect(ics).toContain('BEGIN:VEVENT')
+    expect((ics.match(/BEGIN:VEVENT/g) ?? []).length).toBe(3)
+    expect(ics).toContain('DTSTART:20260706T090000Z')
+    expect(ics).toContain('DTSTART;VALUE=DATE:20260708')
+    expect(ics).toContain('RRULE:FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR')
+    expect(ics).toContain('SUMMARY:Kickoff\\, prep') // comma escaped
+    expect(ics.endsWith('END:VCALENDAR')).toBe(true)
+  })
+
+  it('round-trips events through export -> import', () => {
+    const back = fromICS(toICS(events))
+    expect(back).toHaveLength(3)
+    expect(back[0]!.title).toBe('Kickoff, prep') // unescaped
+    expect(back[0]!.start.toISOString()).toBe('2026-07-06T09:00:00.000Z')
+    expect(back[1]!.allDay).toBe(true)
+    expect(back[2]!.rrule).toMatchObject({ freq: 'weekly', weekdays: [1, 2, 3, 4, 5] })
+  })
+
+  it('imports a hand-written ICS (folded lines + CRLF)', () => {
+    const ics = [
+      'BEGIN:VCALENDAR',
+      'VERSION:2.0',
+      'BEGIN:VEVENT',
+      'UID:z@x',
+      'DTSTART:20260706T140000Z',
+      'DTEND:20260706T150000Z',
+      'SUMMARY:Client call',
+      'END:VEVENT',
+      'END:VCALENDAR',
+    ].join('\r\n')
+    const out = fromICS(ics)
+    expect(out).toHaveLength(1)
+    expect(out[0]!.title).toBe('Client call')
+    expect(out[0]!.end.toISOString()).toBe('2026-07-06T15:00:00.000Z')
+  })
+})

package/src/scheduler-ical.ts

@@ -0,0 +1,180 @@
+/**
+ * scheduler-ical - pure, dependency-free iCalendar (RFC 5545) import / export for
+ * the scheduler. Works on a small {@link ICalEvent} shape so it stays data-model
+ * agnostic: map your rows to/from it. Handles timed + all-day events, RRULE
+ * round-trip (via the shared {@link RecurrenceRule}), STATUS, DESCRIPTION and
+ * LOCATION. No `Date.now()` in the core - `toICS` accepts a stamp.
+ */
+import type { RecurrenceRule } from './recurrence'
+
+export type ICalEvent = {
+  uid?: string
+  title: string
+  description?: string
+  location?: string
+  start: Date
+  end: Date
+  allDay?: boolean
+  status?: 'confirmed' | 'tentative' | 'cancelled'
+  rrule?: RecurrenceRule | null
+}
+
+const WD = ['SU', 'MO', 'TU', 'WE', 'TH', 'FR', 'SA'] as const
+const pad = (n: number) => String(n).padStart(2, '0')
+
+const utcStamp = (d: Date) =>
+  `${d.getUTCFullYear()}${pad(d.getUTCMonth() + 1)}${pad(d.getUTCDate())}T${pad(d.getUTCHours())}${pad(d.getUTCMinutes())}${pad(d.getUTCSeconds())}Z`
+const dateOnly = (d: Date) => `${d.getUTCFullYear()}${pad(d.getUTCMonth() + 1)}${pad(d.getUTCDate())}`
+
+const escText = (s: string) =>
+  s.replace(/\\/g, '\\\\').replace(/;/g, '\\;').replace(/,/g, '\\,').replace(/\r?\n/g, '\\n')
+const unescText = (s: string) =>
+  s.replace(/\\n/gi, '\n').replace(/\\,/g, ',').replace(/\\;/g, ';').replace(/\\\\/g, '\\')
+
+/** Fold a content line at 74 octets (RFC 5545 line folding). */
+function fold(line: string): string {
+  if (line.length <= 74) return line
+  let out = line.slice(0, 74)
+  let rest = line.slice(74)
+  while (rest.length > 73) {
+    out += '\r\n ' + rest.slice(0, 73)
+    rest = rest.slice(73)
+  }
+  return out + '\r\n ' + rest
+}
+
+// --- RRULE serialize / parse ------------------------------------------------
+
+/** A {@link RecurrenceRule} -> an iCal `RRULE` value (without the `RRULE:` name). */
+export function ruleToRRule(rule: RecurrenceRule): string {
+  const parts = [`FREQ=${rule.freq.toUpperCase()}`]
+  if (rule.interval && rule.interval > 1) parts.push(`INTERVAL=${rule.interval}`)
+  if (rule.weekdays?.length) {
+    if (rule.weekOfMonth != null && rule.weekdays.length === 1) {
+      parts.push(`BYDAY=${rule.weekOfMonth}${WD[rule.weekdays[0]!]}`)
+    } else {
+      parts.push(`BYDAY=${rule.weekdays.map((w) => WD[w]).join(',')}`)
+    }
+  }
+  if (rule.day != null && rule.weekOfMonth == null) parts.push(`BYMONTHDAY=${rule.day}`)
+  if (rule.month != null) parts.push(`BYMONTH=${rule.month + 1}`)
+  if (rule.count != null) parts.push(`COUNT=${rule.count}`)
+  if (rule.until != null) parts.push(`UNTIL=${utcStamp(new Date(rule.until as string))}`)
+  return parts.join(';')
+}
+
+/** An iCal `RRULE` value -> a {@link RecurrenceRule}. */
+export function rruleToRule(value: string): RecurrenceRule | null {
+  const map: Record<string, string> = {}
+  for (const kv of value.split(';')) {
+    const [k, v] = kv.split('=')
+    if (k && v) map[k.toUpperCase()] = v
+  }
+  const freq = (map.FREQ ?? '').toLowerCase()
+  if (!['daily', 'weekly', 'monthly', 'yearly'].includes(freq)) return null
+  const rule: RecurrenceRule = { freq: freq as RecurrenceRule['freq'] }
+  if (map.INTERVAL) rule.interval = Number(map.INTERVAL)
+  if (map.BYDAY) {
+    const parts = map.BYDAY.split(',')
+    const m = parts[0]!.match(/^(-?\d+)?([A-Z]{2})$/)
+    if (parts.length === 1 && m && m[1]) {
+      rule.weekOfMonth = Number(m[1])
+      rule.weekdays = [WD.indexOf(m[2] as (typeof WD)[number])]
+    } else {
+      rule.weekdays = parts.map((p) => WD.indexOf(p.replace(/^-?\d+/, '') as (typeof WD)[number])).filter((n) => n >= 0)
+    }
+  }
+  if (map.BYMONTHDAY) rule.day = Number(map.BYMONTHDAY)
+  if (map.BYMONTH) rule.month = Number(map.BYMONTH) - 1
+  if (map.COUNT) rule.count = Number(map.COUNT)
+  if (map.UNTIL) rule.until = parseICalDate(map.UNTIL).date.toISOString()
+  return rule
+}
+
+// --- export -----------------------------------------------------------------
+
+/** Serialize events to an iCalendar string. `stamp` sets DTSTAMP (default epoch). */
+export function toICS(events: ReadonlyArray<ICalEvent>, opts: { prodId?: string; stamp?: Date } = {}): string {
+  const stamp = utcStamp(opts.stamp ?? new Date(0))
+  const lines = ['BEGIN:VCALENDAR', 'VERSION:2.0', `PRODID:${opts.prodId ?? '-//SvGrid//Scheduler//EN'}`]
+  events.forEach((e, i) => {
+    lines.push('BEGIN:VEVENT')
+    lines.push(`UID:${e.uid ?? `svgrid-${i}-${e.start.getTime()}`}`)
+    lines.push(`DTSTAMP:${stamp}`)
+    if (e.allDay) {
+      lines.push(`DTSTART;VALUE=DATE:${dateOnly(e.start)}`)
+      lines.push(`DTEND;VALUE=DATE:${dateOnly(e.end)}`)
+    } else {
+      lines.push(`DTSTART:${utcStamp(e.start)}`)
+      lines.push(`DTEND:${utcStamp(e.end)}`)
+    }
+    lines.push(`SUMMARY:${escText(e.title)}`)
+    if (e.description) lines.push(`DESCRIPTION:${escText(e.description)}`)
+    if (e.location) lines.push(`LOCATION:${escText(e.location)}`)
+    if (e.status) lines.push(`STATUS:${e.status.toUpperCase()}`)
+    if (e.rrule) lines.push(`RRULE:${ruleToRRule(e.rrule)}`)
+    lines.push('END:VEVENT')
+  })
+  lines.push('END:VCALENDAR')
+  return lines.map(fold).join('\r\n')
+}
+
+// --- import -----------------------------------------------------------------
+
+function parseICalDate(value: string): { date: Date; allDay: boolean } {
+  // 20260706 (date) | 20260706T093000Z (utc) | 20260706T093000 (local/floating)
+  const m = value.match(/^(\d{4})(\d{2})(\d{2})(?:T(\d{2})(\d{2})(\d{2})(Z)?)?$/)
+  if (!m) return { date: new Date(NaN), allDay: false }
+  const [, y, mo, d, hh, mm, ss, z] = m
+  if (hh == null) return { date: new Date(Number(y), Number(mo) - 1, Number(d)), allDay: true }
+  if (z) return { date: new Date(Date.UTC(+y!, +mo! - 1, +d!, +hh, +mm!, +ss!)), allDay: false }
+  return { date: new Date(+y!, +mo! - 1, +d!, +hh, +mm!, +ss!), allDay: false }
+}
+
+/** Parse an iCalendar string into events (unfolds lines, reads VEVENT blocks). */
+export function fromICS(text: string): ICalEvent[] {
+  // Unfold: a line starting with space/tab continues the previous one.
+  const raw = text.replace(/\r\n/g, '\n').split('\n')
+  const unfolded: string[] = []
+  for (const line of raw) {
+    if ((line.startsWith(' ') || line.startsWith('\t')) && unfolded.length) {
+      unfolded[unfolded.length - 1] += line.slice(1)
+    } else unfolded.push(line)
+  }
+  const out: ICalEvent[] = []
+  let cur: Partial<ICalEvent> & { _allDayStart?: boolean } = {}
+  let inEvent = false
+  for (const line of unfolded) {
+    if (line === 'BEGIN:VEVENT') {
+      inEvent = true
+      cur = {}
+      continue
+    }
+    if (line === 'END:VEVENT') {
+      if (cur.title && cur.start && cur.end) out.push({ title: cur.title, start: cur.start, end: cur.end, allDay: cur.allDay, uid: cur.uid, description: cur.description, location: cur.location, status: cur.status, rrule: cur.rrule ?? null })
+      inEvent = false
+      continue
+    }
+    if (!inEvent) continue
+    const ci = line.indexOf(':')
+    if (ci < 0) continue
+    const nameAndParams = line.slice(0, ci)
+    const value = line.slice(ci + 1)
+    const name = nameAndParams.split(';')[0]!.toUpperCase()
+    if (name === 'UID') cur.uid = value
+    else if (name === 'SUMMARY') cur.title = unescText(value)
+    else if (name === 'DESCRIPTION') cur.description = unescText(value)
+    else if (name === 'LOCATION') cur.location = unescText(value)
+    else if (name === 'STATUS') cur.status = value.toLowerCase() as ICalEvent['status']
+    else if (name === 'DTSTART') {
+      const { date, allDay } = parseICalDate(value)
+      cur.start = date
+      cur.allDay = allDay
+    } else if (name === 'DTEND') {
+      cur.end = parseICalDate(value).date
+    } else if (name === 'RRULE') {
+      cur.rrule = rruleToRule(value) ?? undefined
+    }
+  }
+  return out
+}