@svgrid/grid 2.1.22 → 2.2.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/overlays.test.ts

@@ -1,90 +1,90 @@
-/**
- * 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)
-      // The wrapper span is never itself focusable, so AT users only ever land
-      // on the real interactive child below - it must carry the description
-      // too, or it's never announced on focus (see SvTooltip.svelte effect).
-      const focusEl = target.querySelector<HTMLElement>('.t')!
-      expect(focusEl.getAttribute('aria-describedby')).toBe(tip.id)
-      destroy()
-    } finally { vi.useRealTimers() }
-  })
-})
+/**
+ * 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)
+      // The wrapper span is never itself focusable, so AT users only ever land
+      // on the real interactive child below - it must carry the description
+      // too, or it's never announced on focus (see SvTooltip.svelte effect).
+      const focusEl = target.querySelector<HTMLElement>('.t')!
+      expect(focusEl.getAttribute('aria-describedby')).toBe(tip.id)
+      destroy()
+    } finally { vi.useRealTimers() }
+  })
+})

package/src/panel-resize.ts

@@ -0,0 +1,52 @@
+/**
+ * panel-resize - the drag math behind a dropdown panel's bottom resize grip
+ * (the "····" handle). Rune-free and DOM-only so every popover select can reuse
+ * it: on the grip's `pointerdown` it tracks the pointer and reports a clamped
+ * height as it moves, releasing its listeners on `pointerup`.
+ *
+ * The grip is only meaningful when the panel opens DOWNWARD (it grows toward the
+ * bottom of the screen); components hide it on an upward flip, where there is no
+ * room below to grow into.
+ */
+
+export type PanelResizeOptions = {
+  /** Panel height (px) at the moment the drag starts. */
+  startHeight: number
+  /** Smallest height the panel may shrink to. Default 80. */
+  min?: number
+  /** Largest height the panel may grow to - the live viewport ceiling. */
+  max: () => number
+  /** Called with the new clamped height on each pointer move. */
+  onHeight: (height: number) => void
+}
+
+/**
+ * Begin a vertical resize from a grip `pointerdown`. Returns nothing; the drag
+ * ends itself on `pointerup`. Safe to call from an `onpointerdown` handler.
+ */
+export function startPanelResize(event: PointerEvent, opts: PanelResizeOptions): void {
+  // Ignore secondary buttons; only a primary drag resizes.
+  if (event.button !== 0) return
+  event.preventDefault()
+  event.stopPropagation()
+  const startY = event.clientY
+  const min = opts.min ?? 80
+
+  const clamp = (h: number) => Math.max(min, Math.min(opts.max(), Math.round(h)))
+  const onMove = (e: PointerEvent) => {
+    opts.onHeight(clamp(opts.startHeight + (e.clientY - startY)))
+  }
+  const onUp = () => {
+    window.removeEventListener('pointermove', onMove)
+    window.removeEventListener('pointerup', onUp)
+    window.removeEventListener('pointercancel', onUp)
+    document.body.style.userSelect = ''
+    document.body.style.cursor = ''
+  }
+  // Suppress text selection + keep the resize cursor for the whole drag.
+  document.body.style.userSelect = 'none'
+  document.body.style.cursor = 'ns-resize'
+  window.addEventListener('pointermove', onMove)
+  window.addEventListener('pointerup', onUp)
+  window.addEventListener('pointercancel', onUp)
+}

package/src/popover.bounds.test.ts

@@ -0,0 +1,93 @@
+/**
+ * Bounds detection for anchored popover panels: flip up/down by available room,
+ * cap the panel height to the viewport, and never let an upward flip start
+ * off-screen. Pairs with the drag math in panel-resize.
+ */
+import { describe, expect, it, beforeAll } from 'vitest'
+import { anchoredRect } from './popover'
+
+const VIEWPORT_H = 800
+const VIEWPORT_W = 1200
+
+beforeAll(() => {
+  Object.defineProperty(window, 'innerHeight', { value: VIEWPORT_H, configurable: true })
+  Object.defineProperty(window, 'innerWidth', { value: VIEWPORT_W, configurable: true })
+})
+
+// Minimal DOMRect stand-in - anchoredRect only reads top/bottom/left/width.
+const rect = (top: number, height: number, left = 100, width = 200) =>
+  ({ top, bottom: top + height, left, width, right: left + width, height, x: left, y: top, toJSON() {} }) as DOMRect
+
+describe('anchoredRect - flip direction', () => {
+  it('opens downward with room below', () => {
+    const r = anchoredRect(rect(100, 32), { estimatedHeight: 280 })
+    expect(r.openUpward).toBe(false)
+    expect(r.top).toBe(132 + 2) // trigger bottom + gap
+  })
+
+  it('flips upward when room below is short and there is more above', () => {
+    // Trigger near the bottom: 60px below, ~740px above.
+    const r = anchoredRect(rect(VIEWPORT_H - 92, 32), { estimatedHeight: 280 })
+    expect(r.openUpward).toBe(true)
+    // Panel sits above the trigger; its top must stay on-screen.
+    expect(r.top).toBeGreaterThanOrEqual(8)
+    expect(r.top).toBeLessThan(VIEWPORT_H - 92)
+  })
+})
+
+describe('anchoredRect - height bounds', () => {
+  it('caps maxHeight to the room below (never overflows the viewport)', () => {
+    // Short viewport so both sides are smaller than the 280 estimate; trigger in
+    // the middle with slightly more room below keeps it opening downward.
+    Object.defineProperty(window, 'innerHeight', { value: 260, configurable: true })
+    try {
+      const r = anchoredRect(rect(110, 32), { estimatedHeight: 280 })
+      // room below = 260 - 142 - gap(2) - margin(8) = 108
+      expect(r.openUpward).toBe(false)
+      expect(r.maxHeight).toBeLessThanOrEqual(108)
+      expect(r.maxHeight).toBeGreaterThan(0)
+      // availHeight is the hard ceiling and is >= the comfortable maxHeight.
+      expect(r.availHeight).toBeGreaterThanOrEqual(r.maxHeight)
+    } finally {
+      Object.defineProperty(window, 'innerHeight', { value: VIEWPORT_H, configurable: true })
+    }
+  })
+
+  it('maxHeight is the estimate when there is ample room', () => {
+    const r = anchoredRect(rect(100, 32), { estimatedHeight: 200 })
+    expect(r.maxHeight).toBe(200)
+    expect(r.availHeight).toBeGreaterThanOrEqual(200)
+  })
+
+  it('never returns a maxHeight below the minHeight floor', () => {
+    // Trigger pinned to the very bottom: almost no room below, lots above -> flips.
+    const r = anchoredRect(rect(VIEWPORT_H - 20, 20), { estimatedHeight: 300, minHeight: 96 })
+    expect(r.maxHeight).toBeGreaterThanOrEqual(96)
+  })
+})
+
+describe('anchoredRect - bottom anchor (natural-height upward panels)', () => {
+  it('returns a bottom offset that pins the panel just above the trigger', () => {
+    // Trigger top at 500, gap 2 -> panel bottom edge at 498 -> bottom offset
+    // from the viewport bottom = 800 - 500 + 2 = 302. Independent of any height
+    // estimate, so a bottom-anchored panel grows to its real content height.
+    const r = anchoredRect(rect(500, 32), { estimatedHeight: 999 })
+    expect(r.bottom).toBe(VIEWPORT_H - 500 + 2)
+  })
+
+  it('bottom offset does not depend on the (possibly wrong) height estimate', () => {
+    const trigger = rect(600, 30)
+    const a = anchoredRect(trigger, { estimatedHeight: 40 })
+    const b = anchoredRect(trigger, { estimatedHeight: 500 })
+    expect(a.bottom).toBe(b.bottom)
+  })
+})
+
+describe('anchoredRect - horizontal', () => {
+  it('clamps a wide panel within the viewport', () => {
+    const r = anchoredRect(rect(100, 32, VIEWPORT_W - 50, 40), { estimatedHeight: 100, minWidth: 300 })
+    expect(r.width).toBe(300)
+    expect(r.left + r.width).toBeLessThanOrEqual(VIEWPORT_W)
+    expect(r.left).toBeGreaterThanOrEqual(4)
+  })
+})

package/src/popover.ts

@@ -68,7 +68,31 @@ export function popIn(node: HTMLElement, param: { up?: boolean; duration?: numbe
   return {}
 }
 
-export type AnchoredRect = { top: number; left: number; width: number; openUpward: boolean }
+export type AnchoredRect = {
+  top: number
+  left: number
+  width: number
+  openUpward: boolean
+  /**
+   * Comfortable panel height: the estimate, capped to the room on the chosen
+   * side so the panel never leaves the viewport. Apply as the panel's
+   * `max-height` and long content scrolls inside instead of overflowing.
+   */
+  maxHeight: number
+  /**
+   * Absolute height the panel may occupy on the chosen side (room minus the
+   * viewport margin). The hard ceiling a user resize must clamp to.
+   */
+  availHeight: number
+  /**
+   * For an upward-flipped panel: distance from the viewport bottom to where the
+   * panel's bottom edge sits (just above the trigger). Bottom-anchoring an
+   * upward panel with `style:bottom` lets it grow to its natural content height
+   * instead of being positioned from a (possibly wrong) height estimate.
+   * Undefined until `anchoredRect` computes it.
+   */
+  bottom?: number
+}
 
 export type AnchorOptions = {
   /** Estimated panel height, used to decide whether to flip upward. */
@@ -79,19 +103,30 @@ export type AnchorOptions = {
   minWidth?: number
   /** Keep the panel within the viewport horizontally. Default true. */
   clampHorizontal?: boolean
+  /** Viewport edge kept clear top/bottom so a panel never touches it. Default 8. */
+  viewportMargin?: number
+  /** Floor for `maxHeight`/`availHeight` so a cramped panel stays usable. Default 96. */
+  minHeight?: number
 }
 
 /**
  * Compute a `position: fixed` rect anchored to `triggerRect`, flipping above the
- * trigger when there isn't room below and there's more room above. Mirrors the
- * behavior SvGridDropdown shipped with, generalized with min-width + horizontal
- * clamping for wider panels (date/time popovers).
+ * trigger when there isn't room below and there's more room above. Generalized
+ * with min-width + horizontal clamping for wider panels (date/time popovers),
+ * and with vertical bounds detection: `maxHeight` caps the panel to the room on
+ * the chosen side (minus a viewport margin) so a long list near a screen edge
+ * scrolls internally rather than overflowing, and an upward flip is clamped so
+ * its top never leaves the viewport.
  */
 export function anchoredRect(triggerRect: DOMRect, opts: AnchorOptions): AnchoredRect {
   const gap = opts.gap ?? 2
-  const spaceBelow = window.innerHeight - triggerRect.bottom
-  const spaceAbove = triggerRect.top
+  const margin = opts.viewportMargin ?? 8
+  const minH = opts.minHeight ?? 96
+  const spaceBelow = window.innerHeight - triggerRect.bottom - gap - margin
+  const spaceAbove = triggerRect.top - gap - margin
   const openUpward = spaceBelow < opts.estimatedHeight && spaceAbove > spaceBelow
+  const availHeight = Math.max(minH, Math.floor(openUpward ? spaceAbove : spaceBelow))
+  const maxHeight = Math.min(opts.estimatedHeight, availHeight)
   const width = Math.max(triggerRect.width, opts.minWidth ?? 0)
   let left = triggerRect.left
   if (opts.clampHorizontal !== false) {
@@ -99,9 +134,18 @@ export function anchoredRect(triggerRect: DOMRect, opts: AnchorOptions): Anchore
     left = Math.max(4, Math.min(left, maxLeft))
   }
   return {
-    top: openUpward ? triggerRect.top - opts.estimatedHeight - gap : triggerRect.bottom + gap,
+    // Upward: pin by the comfortable height and clamp to the top margin so the
+    // panel can never start off-screen. Downward: sit just below the trigger.
+    top: openUpward
+      ? Math.max(margin, triggerRect.top - gap - maxHeight)
+      : triggerRect.bottom + gap,
     left,
     width,
     openUpward,
+    maxHeight,
+    availHeight,
+    // Bottom-anchor value for upward panels: viewport bottom -> panel bottom
+    // edge (which sits `gap` above the trigger top).
+    bottom: Math.round(window.innerHeight - triggerRect.top + gap),
   }
 }

package/src/recurrence.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest'
-import { matchesRecurrence, expandRecurrence, type RecurrenceRule } from './recurrence'
+import { matchesRecurrence, expandRecurrence, describeRecurrence, 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`)
@@ -82,10 +82,97 @@ describe('matchesRecurrence - bounds + combining', () => {
   })
 })
 
+describe('matchesRecurrence - positional weekday-of-month', () => {
+  it('the 1st Tuesday of the month', () => {
+    const r: RecurrenceRule = { freq: 'monthly', weekdays: [2], weekOfMonth: 1 }
+    expect(matchesRecurrence(D('2026-07-07'), r)).toBe(true) // 1st Tue of Jul
+    expect(matchesRecurrence(D('2026-07-14'), r)).toBe(false) // 2nd Tue
+    expect(matchesRecurrence(D('2026-08-04'), r)).toBe(true) // 1st Tue of Aug
+  })
+
+  it('the last Friday of the month', () => {
+    const r: RecurrenceRule = { freq: 'monthly', weekdays: [5], weekOfMonth: -1 }
+    expect(matchesRecurrence(D('2026-07-31'), r)).toBe(true) // last Fri of Jul
+    expect(matchesRecurrence(D('2026-07-24'), r)).toBe(false) // 4th but not last
+    expect(matchesRecurrence(D('2026-08-28'), r)).toBe(true) // last Fri of Aug
+  })
+
+  it('yearly positional: the 2nd Monday of November', () => {
+    const r: RecurrenceRule = { freq: 'yearly', month: 10, weekdays: [1], weekOfMonth: 2 }
+    expect(matchesRecurrence(D('2026-11-09'), r)).toBe(true) // 2nd Mon of Nov 2026
+    expect(matchesRecurrence(D('2026-11-16'), r)).toBe(false) // 3rd Mon
+    expect(matchesRecurrence(D('2026-10-12'), r)).toBe(false) // wrong month
+  })
+})
+
+describe('matchesRecurrence - last day of month + count', () => {
+  it('the last day of the month (day: -1) across month lengths', () => {
+    const r: RecurrenceRule = { freq: 'monthly', day: -1 }
+    expect(matchesRecurrence(D('2026-07-31'), r)).toBe(true) // 31-day month
+    expect(matchesRecurrence(D('2026-02-28'), r)).toBe(true) // 28-day Feb
+    expect(matchesRecurrence(D('2026-02-27'), r)).toBe(false)
+    expect(matchesRecurrence(D('2026-06-30'), r)).toBe(true) // 30-day month
+  })
+
+  it('ends after N occurrences (count)', () => {
+    // 3 weekly Mondays from Jul 6: Jul 6, 13, 20 - then stop.
+    const r: RecurrenceRule = { freq: 'weekly', weekdays: [1], from: D('2026-07-06'), count: 3 }
+    expect(matchesRecurrence(D('2026-07-06'), r)).toBe(true)
+    expect(matchesRecurrence(D('2026-07-20'), r)).toBe(true) // 3rd
+    expect(matchesRecurrence(D('2026-07-27'), r)).toBe(false) // 4th - past the count
+  })
+})
+
 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])
   })
+
+  it('stops after `count` occurrences even in a wider window', () => {
+    const r: RecurrenceRule = { freq: 'weekly', weekdays: [1], from: D('2026-07-06'), count: 3 }
+    const dates = expandRecurrence(r, D('2026-07-01'), D('2026-08-31')).map((d) => d.getDate())
+    expect(dates).toEqual([6, 13, 20]) // exactly 3, not every Monday
+  })
+})
+
+describe('describeRecurrence - human-readable summaries', () => {
+  it('empty / falsy rules read as the never label (default blank)', () => {
+    expect(describeRecurrence(null)).toBe('')
+    expect(describeRecurrence([])).toBe('')
+    expect(describeRecurrence(undefined, { never: 'Does not repeat' })).toBe('Does not repeat')
+  })
+
+  it('daily + weekly', () => {
+    expect(describeRecurrence({ freq: 'daily' })).toBe('Daily')
+    expect(describeRecurrence({ freq: 'daily', interval: 2 })).toBe('Every 2 days')
+    expect(describeRecurrence({ freq: 'weekly', weekdays: [1, 2, 3, 4, 5] })).toBe('Weekly on weekdays')
+    expect(describeRecurrence({ freq: 'weekly', weekdays: [0, 6] })).toBe('Weekly on weekends')
+    expect(describeRecurrence({ freq: 'weekly', weekdays: [1, 3] })).toBe('Weekly on Mon, Wed')
+    expect(describeRecurrence({ freq: 'weekly', weekdays: [5], interval: 2 })).toBe('Every 2 weeks on Fri')
+  })
+
+  it('monthly + yearly, positional + last day', () => {
+    expect(describeRecurrence({ freq: 'monthly', day: 1 })).toBe('Monthly on day 1')
+    expect(describeRecurrence({ freq: 'monthly', day: -1 })).toBe('Monthly on the last day')
+    expect(describeRecurrence({ freq: 'monthly', weekdays: [5], weekOfMonth: -1 })).toBe('Monthly on the last Fri')
+    expect(describeRecurrence({ freq: 'yearly', month: 10, weekdays: [4], weekOfMonth: 4 })).toBe(
+      'Yearly on the fourth Thu of Nov',
+    )
+    expect(describeRecurrence({ freq: 'yearly', month: 11, day: 25 })).toBe('Yearly on day 25 of Dec')
+  })
+
+  it('appends the end condition (count / until)', () => {
+    expect(describeRecurrence({ freq: 'weekly', weekdays: [1], count: 8 })).toBe('Weekly on Mon, 8 times')
+    expect(describeRecurrence({ freq: 'daily', until: D('2026-12-31') })).toBe('Daily until Dec 31, 2026')
+  })
+
+  it('joins a list of rules', () => {
+    const rules: RecurrenceRule[] = [
+      { freq: 'weekly', weekdays: [1] },
+      { freq: 'monthly', day: 1 },
+    ]
+    expect(describeRecurrence(rules)).toBe('Weekly on Mon; Monthly on day 1')
+  })
 })