@svgrid/grid 1.2.33 → 2.0.0

package/src/merge-objects.ts

@@ -1,48 +1,48 @@
-/**
- * Merges objects together while keeping their getters alive.
- * Taken from SolidJS:
- * https://github.com/solidjs/solid/blob/24abc825c0996fd2bc8c1de1491efe9a7e743aff/packages/solid/src/server/rendering.ts#L82-L115
- */
-export function mergeObjects<T>(source: T): T
-export function mergeObjects<T, U>(source: T, source1: U): T & U
-export function mergeObjects<T, U, V>(
-  source: T,
-  source1: U,
-  source2: V,
-): T & U & V
-export function mergeObjects<T, U, V, W>(
-  source: T,
-  source1: U,
-  source2: V,
-  source3: W,
-): T & U & V & W
-export function mergeObjects(...sources: any): any {
-  const target = {}
-
-  for (let source of sources) {
-    if (typeof source === 'function') source = source()
-
-    if (source) {
-      const descriptors = Object.getOwnPropertyDescriptors(source)
-
-      for (const key in descriptors) {
-        if (key in target) continue
-
-        Object.defineProperty(target, key, {
-          enumerable: true,
-          get() {
-            for (let i = sources.length - 1; i >= 0; i--) {
-              let scopedSource = sources[i]
-              if (typeof scopedSource === 'function') scopedSource = scopedSource()
-
-              const value = (scopedSource || {})[key]
-              if (value !== undefined) return value
-            }
-          },
-        })
-      }
-    }
-  }
-
-  return target
-}
+/**
+ * Merges objects together while keeping their getters alive.
+ * Taken from SolidJS:
+ * https://github.com/solidjs/solid/blob/24abc825c0996fd2bc8c1de1491efe9a7e743aff/packages/solid/src/server/rendering.ts#L82-L115
+ */
+export function mergeObjects<T>(source: T): T
+export function mergeObjects<T, U>(source: T, source1: U): T & U
+export function mergeObjects<T, U, V>(
+  source: T,
+  source1: U,
+  source2: V,
+): T & U & V
+export function mergeObjects<T, U, V, W>(
+  source: T,
+  source1: U,
+  source2: V,
+  source3: W,
+): T & U & V & W
+export function mergeObjects(...sources: any): any {
+  const target = {}
+
+  for (let source of sources) {
+    if (typeof source === 'function') source = source()
+
+    if (source) {
+      const descriptors = Object.getOwnPropertyDescriptors(source)
+
+      for (const key in descriptors) {
+        if (key in target) continue
+
+        Object.defineProperty(target, key, {
+          enumerable: true,
+          get() {
+            for (let i = sources.length - 1; i >= 0; i--) {
+              let scopedSource = sources[i]
+              if (typeof scopedSource === 'function') scopedSource = scopedSource()
+
+              const value = (scopedSource || {})[key]
+              if (value !== undefined) return value
+            }
+          },
+        })
+      }
+    }
+  }
+
+  return target
+}

package/src/otp.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest'
+import { sanitizeOtp, otpCells, isOtpComplete } from './otp'
+
+describe('sanitizeOtp', () => {
+  it('keeps only digits in numeric mode and clamps to length', () => {
+    expect(sanitizeOtp('12ab34-56', 4, true)).toBe('1234')
+  })
+  it('keeps non-whitespace in text mode', () => {
+    expect(sanitizeOtp('a b\tc d', 3, false)).toBe('abc')
+  })
+  it('clamps to length', () => {
+    expect(sanitizeOtp('123456789', 6, true)).toBe('123456')
+  })
+})
+
+describe('otpCells', () => {
+  it('pads to exactly length cells', () => {
+    expect(otpCells('12', 4)).toEqual(['1', '2', '', ''])
+  })
+})
+
+describe('isOtpComplete', () => {
+  it('is true only when every cell is filled', () => {
+    expect(isOtpComplete('1234', 4)).toBe(true)
+    expect(isOtpComplete('12', 4)).toBe(false)
+    expect(isOtpComplete('', 4)).toBe(false)
+  })
+})

package/src/otp.ts

@@ -0,0 +1,28 @@
+/**
+ * otp - pure helpers behind <SvOtpInput>: sanitize/spread a raw string across N
+ * segments (used on paste and per-cell input) and detect completion.
+ * Framework-free + pure so they are unit-tested directly.
+ */
+
+/**
+ * Keep only the characters allowed for `numeric` mode (digits) or any
+ * non-whitespace otherwise, then clamp to `length`. Returns the cleaned string
+ * (<= length chars).
+ */
+export function sanitizeOtp(raw: string, length: number, numeric: boolean): string {
+  const kept = numeric ? raw.replace(/\D/g, '') : raw.replace(/\s/g, '')
+  return kept.slice(0, Math.max(0, length))
+}
+
+/** Split a value into exactly `length` single-char cells (padding with ''). */
+export function otpCells(value: string, length: number): string[] {
+  const cells: string[] = []
+  for (let i = 0; i < length; i++) cells[i] = value[i] ?? ''
+  return cells
+}
+
+/** Whether `value` fills every cell (a joined OTP has no internal gaps, so an
+ *  exact-length string is complete). */
+export function isOtpComplete(value: string, length: number): boolean {
+  return value.length === length
+}

package/src/overlays.test.ts

@@ -0,0 +1,85 @@
+/**
+ * Component tests for the overlay trio: SvModal (dialog semantics, Escape /
+ * backdrop close), SvPopover (click open + outside close) and SvTooltip
+ * (focus-triggered, aria-describedby wiring).
+ */
+import { describe, expect, it, vi, afterEach } from 'vitest'
+import { mount, unmount, flushSync, createRawSnippet } from 'svelte'
+import SvModal from './SvModal.svelte'
+import SvPopover from './SvPopover.svelte'
+import SvTooltip from './SvTooltip.svelte'
+
+const body = createRawSnippet(() => ({ render: () => `<p class="body">hello</p>` }))
+const anchorBtn = createRawSnippet(() => ({ render: () => `<button class="anchor">open</button>` }))
+
+function mountC(Comp: any, props: Record<string, unknown>) {
+  const target = document.createElement('div')
+  document.body.appendChild(target)
+  const app = mount(Comp, { target, props: props as any })
+  flushSync()
+  return { target, destroy: () => { unmount(app); target.remove() } }
+}
+afterEach(() => {
+  document.querySelectorAll('.sv-modal__backdrop, .sv-pop__panel, .sv-tip').forEach((n) => n.remove())
+})
+
+describe('SvModal', () => {
+  it('renders a labelled modal dialog when open', () => {
+    const { destroy } = mountC(SvModal, { open: true, title: 'Edit', children: body })
+    try {
+      const dialog = document.querySelector<HTMLElement>('.sv-modal')!
+      expect(dialog.getAttribute('role')).toBe('dialog')
+      expect(dialog.getAttribute('aria-modal')).toBe('true')
+      const titleId = dialog.getAttribute('aria-labelledby')!
+      expect(document.getElementById(titleId)!.textContent).toBe('Edit')
+      expect(document.querySelector('.sv-modal .body')!.textContent).toBe('hello')
+    } finally { destroy() }
+  })
+
+  it('Escape and the close button both fire onClose', () => {
+    let closed = 0
+    const { destroy } = mountC(SvModal, { open: true, title: 'X', onClose: () => (closed++), children: body })
+    try {
+      document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape' }))
+      flushSync()
+      expect(closed).toBe(1)
+    } finally { destroy() }
+  })
+})
+
+describe('SvPopover', () => {
+  it('opens the panel on anchor click and closes on outside pointerdown', () => {
+    const { target, destroy } = mountC(SvPopover, { anchor: anchorBtn, children: body })
+    try {
+      expect(document.querySelector('.sv-pop__panel')).toBeNull()
+      target.querySelector<HTMLElement>('.anchor')!.click()
+      flushSync()
+      const panel = document.querySelector<HTMLElement>('.sv-pop__panel')!
+      expect(panel).not.toBeNull()
+      expect(panel.getAttribute('role')).toBe('dialog')
+      // Outside click closes.
+      document.dispatchEvent(new PointerEvent('pointerdown', { bubbles: true }))
+      flushSync()
+      expect(document.querySelector('.sv-pop__panel')).toBeNull()
+    } finally { destroy() }
+  })
+})
+
+describe('SvTooltip', () => {
+  it('shows after the delay on focus and wires aria-describedby', () => {
+    vi.useFakeTimers()
+    try {
+      const child = createRawSnippet(() => ({ render: () => `<button class="t">i</button>` }))
+      const { target, destroy } = mountC(SvTooltip, { text: 'Tip text', delay: 200, children: child })
+      const anchor = target.querySelector<HTMLElement>('.sv-tip__anchor')!
+      anchor.dispatchEvent(new FocusEvent('focusin', { bubbles: true }))
+      vi.advanceTimersByTime(210)
+      flushSync()
+      const tip = document.querySelector<HTMLElement>('.sv-tip')!
+      expect(tip).not.toBeNull()
+      expect(tip.getAttribute('role')).toBe('tooltip')
+      expect(anchor.getAttribute('aria-describedby')).toBe(tip.id)
+      destroy()
+    } finally { vi.useRealTimers() }
+  })
+})

package/src/paginate.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from 'vitest'
+import { paginationRange } from './paginate'
+
+describe('paginationRange', () => {
+  it('returns an empty list for zero pages', () => {
+    expect(paginationRange({ page: 1, pageCount: 0 })).toEqual([])
+  })
+
+  it('shows every page when the count is small', () => {
+    expect(paginationRange({ page: 3, pageCount: 5 })).toEqual([1, 2, 3, 4, 5])
+  })
+
+  it('adds a trailing ellipsis near the start', () => {
+    expect(paginationRange({ page: 1, pageCount: 10 })).toEqual([1, 2, 'ellipsis-right', 10])
+  })
+
+  it('adds ellipses on both sides in the middle', () => {
+    expect(paginationRange({ page: 5, pageCount: 10 })).toEqual([
+      1, 'ellipsis-left', 4, 5, 6, 'ellipsis-right', 10,
+    ])
+  })
+
+  it('adds a leading ellipsis near the end', () => {
+    expect(paginationRange({ page: 10, pageCount: 10 })).toEqual([1, 'ellipsis-left', 9, 10])
+  })
+
+  it('collapses a single-page gap to that page number, not an ellipsis', () => {
+    // Between boundary 1 and sibling-start 3 there is exactly one page (2): show it.
+    expect(paginationRange({ page: 4, pageCount: 8 })).toEqual([1, 2, 3, 4, 5, 'ellipsis-right', 8])
+  })
+
+  it('clamps an out-of-range page', () => {
+    expect(paginationRange({ page: 99, pageCount: 5 })).toEqual([1, 2, 3, 4, 5])
+  })
+
+  it('honours a larger siblingCount', () => {
+    expect(paginationRange({ page: 6, pageCount: 12, siblingCount: 2 })).toEqual([
+      1, 'ellipsis-left', 4, 5, 6, 7, 8, 'ellipsis-right', 12,
+    ])
+  })
+})

package/src/paginate.ts

@@ -0,0 +1,61 @@
+/**
+ * paginate - the pure page-range algorithm behind <SvPagination>. Given the
+ * current page and total page count, returns the sequence of page numbers and
+ * ellipsis markers to render (boundary pages + a window of siblings around the
+ * current page, with gaps collapsed to an ellipsis). Framework-free + pure so
+ * it is unit-tested on its own.
+ */
+export type PaginationItem = number | 'ellipsis-left' | 'ellipsis-right'
+
+export type PaginationRangeOptions = {
+  /** 1-based current page. */
+  page: number
+  /** Total number of pages. */
+  pageCount: number
+  /** Pages shown on each side of the current page. Default 1. */
+  siblingCount?: number
+  /** Pages pinned at each end. Default 1. */
+  boundaryCount?: number
+}
+
+const clamp = (n: number, lo: number, hi: number) => Math.min(Math.max(n, lo), hi)
+
+/** Build the page/ellipsis sequence (e.g. `[1, 'ellipsis-left', 4, 5, 6, 'ellipsis-right', 20]`). */
+export function paginationRange(options: PaginationRangeOptions): PaginationItem[] {
+  const { pageCount } = options
+  if (pageCount <= 0) return []
+  const siblingCount = Math.max(0, options.siblingCount ?? 1)
+  const boundaryCount = Math.max(1, options.boundaryCount ?? 1)
+  const page = clamp(options.page, 1, pageCount)
+
+  // If ellipsis could hide at most one page, just show every page.
+  if (pageCount <= boundaryCount * 2 + siblingCount * 2 + 3) {
+    return Array.from({ length: pageCount }, (_, i) => i + 1)
+  }
+
+  const pages = new Set<number>()
+  // End boundaries (both ends).
+  for (let i = 1; i <= boundaryCount && i <= pageCount; i++) {
+    pages.add(i)
+    pages.add(pageCount - i + 1)
+  }
+  // Siblings around the current page.
+  for (let i = page - siblingCount; i <= page + siblingCount; i++) {
+    if (i >= 1 && i <= pageCount) pages.add(i)
+  }
+
+  const sorted = [...pages].sort((a, b) => a - b)
+  const result: PaginationItem[] = []
+  let prev = 0
+  for (const p of sorted) {
+    if (p - prev === 2) {
+      // Exactly one page in the gap: show it instead of an ellipsis.
+      result.push(prev + 1)
+    } else if (p - prev > 2) {
+      result.push(p <= page ? 'ellipsis-left' : 'ellipsis-right')
+    }
+    result.push(p)
+    prev = p
+  }
+  return result
+}

package/src/phone-valid.test.ts

@@ -0,0 +1,26 @@
+/**
+ * Per-country phone length validation (phoneDigitsValid): exact lengths, ranges,
+ * unknown countries (any non-empty), and empty handling.
+ */
+import { describe, expect, it } from 'vitest'
+import { phoneDigitsValid } from './countries'
+
+describe('phoneDigitsValid', () => {
+  it('checks exact national lengths', () => {
+    expect(phoneDigitsValid('US', '4155551234')).toBe(true) // 10
+    expect(phoneDigitsValid('US', '415555')).toBe(false)
+    expect(phoneDigitsValid('IN', '9876543210')).toBe(true) // 10
+    expect(phoneDigitsValid('SG', '81234567')).toBe(true) // 8
+    expect(phoneDigitsValid('SG', '8123456')).toBe(false)
+  })
+  it('accepts ranges', () => {
+    expect(phoneDigitsValid('DE', '1701234567')).toBe(true) // 10 in [10,11]
+    expect(phoneDigitsValid('DE', '17012345678')).toBe(true) // 11
+    expect(phoneDigitsValid('DE', '170')).toBe(false)
+  })
+  it('ignores non-digits and unknown countries', () => {
+    expect(phoneDigitsValid('US', '(415) 555-1234')).toBe(true)
+    expect(phoneDigitsValid('ZZ', '12345')).toBe(true) // unknown -> any non-empty
+    expect(phoneDigitsValid('ZZ', '')).toBe(false)
+  })
+})

package/src/popover.ts

@@ -16,9 +16,12 @@
  * any popover panel actually consumes.
  */
 export const PANEL_THEME_VARS = [
-  '--sg-accent', '--sg-bg', '--sg-fg', '--sg-border', '--sg-muted',
-  '--sg-header-bg', '--sg-row-hover-bg', '--sg-selection-bg',
-  '--sg-input-bg', '--sg-input-border', '--sg-selection-fg',
+  '--sg-accent', '--sg-on-accent', '--sg-bg', '--sg-fg', '--sg-muted', '--sg-border',
+  '--sg-header-bg', '--sg-header-fg', '--sg-row-hover-bg', '--sg-row-alt-bg',
+  '--sg-selection-bg', '--sg-selection-fg', '--sg-input-bg', '--sg-input-border',
+  '--sg-danger', '--sg-focus-ring', '--sg-radius', '--sg-font',
+  '--sg-invalid-bg', '--sg-invalid-border', '--sg-invalid-fg',
+  '--sg-rating-on', '--sg-rating-empty', '--sg-rating-hover',
 ] as const
 
 /**
@@ -40,6 +43,31 @@ export function portalToBody(node: HTMLElement, vars: ReadonlyArray<string> = PA
   }
 }
 
+/**
+ * Svelte action: play a short enter animation when a portalled panel mounts
+ * (dropdowns, popovers, dialogs). Slides from the trigger side + fades/scales in.
+ * A no-op under `prefers-reduced-motion` and in environments without the Web
+ * Animations API (jsdom), so tests and reduced-motion users are unaffected.
+ *
+ * `use:popIn={{ up: rect.openUpward }}` - pass `up` for panels that flipped above
+ * their trigger so the slide direction matches.
+ */
+export function popIn(node: HTMLElement, param: { up?: boolean; duration?: number; scale?: number } = {}) {
+  if (typeof node.animate !== 'function') return
+  const reduce = typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches
+  if (reduce) return
+  const dy = param.up ? 6 : -6
+  const s = param.scale ?? 0.97
+  node.animate(
+    [
+      { opacity: 0, transform: `translateY(${dy}px) scale(${s})` },
+      { opacity: 1, transform: 'translateY(0) scale(1)' },
+    ],
+    { duration: param.duration ?? 140, easing: 'cubic-bezier(0.16, 1, 0.3, 1)' },
+  )
+  return {}
+}
+
 export type AnchoredRect = { top: number; left: number; width: number; openUpward: boolean }
 
 export type AnchorOptions = {

package/src/progress.test.ts

@@ -0,0 +1,55 @@
+/**
+ * Component tests for SvProgress + SvCircularProgress: progressbar ARIA,
+ * determinate fill width / ring offset, and indeterminate (no valuenow).
+ */
+import { describe, expect, it } from 'vitest'
+import { mount, unmount, flushSync } from 'svelte'
+import SvProgress from './SvProgress.svelte'
+import SvCircularProgress from './SvCircularProgress.svelte'
+
+function mountC(Comp: any, props: Record<string, unknown>) {
+  const target = document.createElement('div')
+  document.body.appendChild(target)
+  const app = mount(Comp, { target, props: props as any })
+  flushSync()
+  return { target, destroy: () => { unmount(app); target.remove() } }
+}
+
+describe('SvProgress', () => {
+  it('exposes progressbar ARIA + fill width for a determinate value', () => {
+    const { target, destroy } = mountC(SvProgress, { value: 40, max: 200, showLabel: true })
+    try {
+      const bar = target.querySelector<HTMLElement>('[role="progressbar"]')!
+      expect(bar.getAttribute('aria-valuemin')).toBe('0')
+      expect(bar.getAttribute('aria-valuemax')).toBe('200')
+      expect(bar.getAttribute('aria-valuenow')).toBe('40')
+      expect(target.querySelector<HTMLElement>('.sv-prog__fill')!.style.width).toBe('20%')
+      expect(target.querySelector('.sv-prog__label')!.textContent).toBe('20%')
+    } finally { destroy() }
+  })
+
+  it('indeterminate drops valuenow and animates', () => {
+    const { target, destroy } = mountC(SvProgress, { indeterminate: true })
+    try {
+      const bar = target.querySelector<HTMLElement>('[role="progressbar"]')!
+      expect(bar.getAttribute('aria-valuenow')).toBeNull()
+      expect(target.querySelector('.sv-prog__fill.is-indeterminate')).not.toBeNull()
+    } finally { destroy() }
+  })
+})
+
+describe('SvCircularProgress', () => {
+  it('sets the ring dashoffset from the value', () => {
+    const { target, destroy } = mountC(SvCircularProgress, { value: 75, size: 48, thickness: 4, showLabel: true })
+    try {
+      const bar = target.querySelector<HTMLElement>('[role="progressbar"]')!
+      expect(bar.getAttribute('aria-valuenow')).toBe('75')
+      const arc = target.querySelector<SVGCircleElement>('.sv-circ__arc')!
+      const circ = 2 * Math.PI * ((48 - 4) / 2)
+      expect(Number(arc.getAttribute('stroke-dasharray'))).toBeCloseTo(circ, 3)
+      // 75% -> 25% of the circumference remains as offset.
+      expect(Number(arc.getAttribute('stroke-dashoffset'))).toBeCloseTo(circ * 0.25, 3)
+      expect(target.querySelector('.sv-circ__label')!.textContent).toBe('75%')
+    } finally { destroy() }
+  })
+})

package/src/recurrence.test.ts

@@ -0,0 +1,91 @@
+import { describe, expect, it } from 'vitest'
+import { matchesRecurrence, expandRecurrence, type RecurrenceRule } from './recurrence'
+
+// Fixed reference dates (local time). 2026-07-01 is a Wednesday.
+const D = (s: string) => new Date(`${s}T00:00:00`)
+
+describe('matchesRecurrence - weekly', () => {
+  const weekdays: RecurrenceRule = { freq: 'weekly', weekdays: [1, 2, 3, 4, 5] } // Mon..Fri
+  it('matches weekdays, not weekends', () => {
+    expect(matchesRecurrence(D('2026-07-06'), weekdays)).toBe(true) // Monday
+    expect(matchesRecurrence(D('2026-07-10'), weekdays)).toBe(true) // Friday
+    expect(matchesRecurrence(D('2026-07-11'), weekdays)).toBe(false) // Saturday
+    expect(matchesRecurrence(D('2026-07-12'), weekdays)).toBe(false) // Sunday
+  })
+
+  it('every other Monday with an interval + anchor', () => {
+    const r: RecurrenceRule = { freq: 'weekly', weekdays: [1], interval: 2, from: D('2026-07-06') }
+    expect(matchesRecurrence(D('2026-07-06'), r)).toBe(true) // anchor Monday
+    expect(matchesRecurrence(D('2026-07-13'), r)).toBe(false) // next Monday (odd week)
+    expect(matchesRecurrence(D('2026-07-20'), r)).toBe(true) // +2 weeks
+    expect(matchesRecurrence(D('2026-07-07'), r)).toBe(false) // Tuesday
+  })
+
+  it("falls back to the anchor's weekday when no weekdays given", () => {
+    const r: RecurrenceRule = { freq: 'weekly', from: D('2026-07-01') } // Wednesday
+    expect(matchesRecurrence(D('2026-07-08'), r)).toBe(true) // Wednesday
+    expect(matchesRecurrence(D('2026-07-09'), r)).toBe(false) // Thursday
+  })
+})
+
+describe('matchesRecurrence - monthly / yearly / daily', () => {
+  it('monthly on a day-of-month', () => {
+    const r: RecurrenceRule = { freq: 'monthly', day: 1 }
+    expect(matchesRecurrence(D('2026-07-01'), r)).toBe(true)
+    expect(matchesRecurrence(D('2026-08-01'), r)).toBe(true)
+    expect(matchesRecurrence(D('2026-08-02'), r)).toBe(false)
+  })
+
+  it('monthly with an interval + anchor (every 3 months, the 15th)', () => {
+    const r: RecurrenceRule = { freq: 'monthly', day: 15, interval: 3, from: D('2026-01-15') }
+    expect(matchesRecurrence(D('2026-01-15'), r)).toBe(true)
+    expect(matchesRecurrence(D('2026-02-15'), r)).toBe(false)
+    expect(matchesRecurrence(D('2026-04-15'), r)).toBe(true)
+  })
+
+  it('yearly on a month + day', () => {
+    const r: RecurrenceRule = { freq: 'yearly', month: 11, day: 25 } // Dec 25
+    expect(matchesRecurrence(D('2026-12-25'), r)).toBe(true)
+    expect(matchesRecurrence(D('2027-12-25'), r)).toBe(true)
+    expect(matchesRecurrence(D('2026-12-24'), r)).toBe(false)
+  })
+
+  it('daily every N days from an anchor', () => {
+    const r: RecurrenceRule = { freq: 'daily', interval: 3, from: D('2026-07-01') }
+    expect(matchesRecurrence(D('2026-07-01'), r)).toBe(true)
+    expect(matchesRecurrence(D('2026-07-02'), r)).toBe(false)
+    expect(matchesRecurrence(D('2026-07-04'), r)).toBe(true)
+  })
+})
+
+describe('matchesRecurrence - bounds + combining', () => {
+  it('respects from / until', () => {
+    const r: RecurrenceRule = { freq: 'daily', from: D('2026-07-05'), until: D('2026-07-08') }
+    expect(matchesRecurrence(D('2026-07-04'), r)).toBe(false) // before
+    expect(matchesRecurrence(D('2026-07-06'), r)).toBe(true) // inside
+    expect(matchesRecurrence(D('2026-07-09'), r)).toBe(false) // after until
+  })
+
+  it('matches if ANY rule in a list matches', () => {
+    const rules: RecurrenceRule[] = [
+      { freq: 'weekly', weekdays: [1] }, // Mondays
+      { freq: 'monthly', day: 1 }, // the 1st
+    ]
+    expect(matchesRecurrence(D('2026-07-06'), rules)).toBe(true) // Monday
+    expect(matchesRecurrence(D('2026-07-01'), rules)).toBe(true) // the 1st (a Wednesday)
+    expect(matchesRecurrence(D('2026-07-02'), rules)).toBe(false)
+  })
+
+  it('returns false for empty / nullish rules', () => {
+    expect(matchesRecurrence(D('2026-07-01'), null)).toBe(false)
+    expect(matchesRecurrence(D('2026-07-01'), [])).toBe(false)
+  })
+})
+
+describe('expandRecurrence', () => {
+  it('lists the matching dates in a range', () => {
+    const r: RecurrenceRule = { freq: 'weekly', weekdays: [1] } // Mondays
+    const dates = expandRecurrence(r, D('2026-07-01'), D('2026-07-31')).map((d) => d.getDate())
+    expect(dates).toEqual([6, 13, 20, 27])
+  })
+})