@svgrid/grid 2.1.21 → 2.1.23

package/src/list-nav.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest'
+import { enabledIndices, wrapMove } from './list-nav'
+
+describe('enabledIndices', () => {
+  it('lists every index when nothing is disabled', () => {
+    expect(enabledIndices(3)).toEqual([0, 1, 2])
+  })
+
+  it('skips indices the predicate marks disabled', () => {
+    expect(enabledIndices(5, (i) => i === 1 || i === 3)).toEqual([0, 2, 4])
+  })
+
+  it('returns an empty array for a zero count', () => {
+    expect(enabledIndices(0)).toEqual([])
+  })
+})
+
+describe('wrapMove', () => {
+  const list = [0, 2, 4] // e.g. indices 1 and 3 are disabled
+
+  it('moves forward to the next enabled index', () => {
+    expect(wrapMove(list, 2, 1)).toBe(4)
+  })
+
+  it('wraps past the end back to the head', () => {
+    expect(wrapMove(list, 4, 1)).toBe(0)
+  })
+
+  it('wraps before the head to the tail', () => {
+    expect(wrapMove(list, 0, -1)).toBe(4)
+  })
+
+  it('from an absent current, delta 1 lands on the first entry', () => {
+    expect(wrapMove(list, -1, 1)).toBe(0)
+  })
+
+  it('from an absent current, delta -1 lands on the last-but-one', () => {
+    expect(wrapMove(list, -1, -1)).toBe(2)
+  })
+
+  it('stays put for a single-entry list', () => {
+    expect(wrapMove([5], 5, 1)).toBe(5)
+    expect(wrapMove([5], 5, -1)).toBe(5)
+  })
+
+  it('returns -1 for an empty list', () => {
+    expect(wrapMove([], 0, 1)).toBe(-1)
+  })
+})

package/src/list-nav.ts

@@ -0,0 +1,29 @@
+/**
+ * list-nav - the pure, framework-free navigation math shared by the roving-focus
+ * cores (createListbox, createPopoverSelect, createMenu). No runes, no DOM - just
+ * index arithmetic, so it is unit-testable on its own and behaves identically
+ * everywhere. The cores wrap these in `$state`.
+ */
+
+/** Indices of items that can take roving focus / selection - i.e. the ones the
+ *  caller does not mark disabled. `count` is the total item count; `isDisabled`
+ *  is consulted per index (a separator counts as disabled to the caller). */
+export function enabledIndices(count: number, isDisabled?: (index: number) => boolean): number[] {
+  const out: number[] = []
+  for (let i = 0; i < count; i++) if (!isDisabled?.(i)) out.push(i)
+  return out
+}
+
+/**
+ * The next index when moving `delta` steps through `list`, wrapping around the
+ * ends. `current` need not be in `list` (it may sit on a disabled item): when it
+ * is absent we start just before the head so `delta: 1` lands on the first entry
+ * and `delta: -1` on the last-but-one - the same behaviour every existing core
+ * already had. Returns `-1` for an empty list.
+ */
+export function wrapMove(list: readonly number[], current: number, delta: number): number {
+  const len = list.length
+  if (len === 0) return -1
+  const pos = list.indexOf(current)
+  return list[(pos + delta + len) % len]!
+}

package/src/list-option.ts

@@ -5,6 +5,8 @@ export type ListOption = {
   disabled?: boolean
   /** Optional group heading this option belongs under. */
   group?: string
+  /** Optional color swatch (any CSS color) shown before the label. */
+  color?: string
 }
 
 /** Case-insensitive substring filter over option labels. */

package/src/menu-item.ts

@@ -0,0 +1,21 @@
+import type { Snippet } from 'svelte'
+
+/**
+ * A single item in a menu (SvMenu / SvMenuList / SvContextMenu) and the headless
+ * `createMenu` core. Kept in a plain `.ts` module so the core can import the type
+ * without pulling in the `.svelte` component - which would create a
+ * `.svelte.ts` -> `.svelte` -> `.svelte.ts` import cycle that Vite's dev-time
+ * import-analysis fails to resolve.
+ */
+export type MenuItem = {
+  /** Item text. Omit + set `separator` for a divider. */
+  label?: string
+  separator?: boolean
+  icon?: Snippet
+  /** Right-aligned hint, e.g. a keyboard shortcut. */
+  shortcut?: string
+  disabled?: boolean
+  /** Nested submenu items (renders a flyout). */
+  children?: MenuItem[]
+  onSelect?: () => void
+}

package/src/menus.test.ts

@@ -98,6 +98,54 @@ describe('createMenus - filter row/menu value updates', () => {
     expect(ctx.filterRowValues.name).toBe('foo')
   })
 
+  it('addFilterToken builds a newline-serialised in/notIn list, ignoring dupes/blanks', () => {
+    const ctx = makeCtx()
+    const m = createMenus(ctx)
+    m.addFilterToken('symbol', 'TSM')
+    m.addFilterToken('symbol', 'BP')
+    m.addFilterToken('symbol', 'TSM') // dupe - ignored
+    m.addFilterToken('symbol', '   ') // blank - ignored
+    expect(ctx.filterRowValues.symbol).toBe('TSM\nBP')
+    // mirrored into the menu model too, so both filter surfaces agree
+    expect(ctx.filterMenuValues.symbol.value).toBe('TSM\nBP')
+  })
+
+  it('removeFilterToken drops a value from the list', () => {
+    const ctx = makeCtx({ filterRowValues: { symbol: 'TSM\nBP\nBABA' } })
+    const m = createMenus(ctx)
+    m.removeFilterToken('symbol', 'BP')
+    expect(ctx.filterRowValues.symbol).toBe('TSM\nBABA')
+  })
+
+  it('toggleFilterToken adds when absent and removes when present', () => {
+    const ctx = makeCtx()
+    const m = createMenus(ctx)
+    m.toggleFilterToken('symbol', 'BP')
+    expect(ctx.filterRowValues.symbol).toBe('BP')
+    m.toggleFilterToken('symbol', 'BP')
+    expect(ctx.filterRowValues.symbol).toBe('')
+  })
+
+  it('openInSuggest anchors the dropdown and targets the column; closeInSuggest clears it', () => {
+    const ctx = makeCtx()
+    const m = createMenus(ctx)
+    const anchor = {
+      getBoundingClientRect: () => ({ left: 40, bottom: 80 }),
+    } as unknown as HTMLElement
+    m.openInSuggest(anchor, 'symbol')
+    expect(ctx.inSuggestFor).toBe('symbol')
+    expect(ctx.inSuggestPos).toMatchObject({ y: 84 })
+    m.closeInSuggest()
+    expect(ctx.inSuggestFor).toBe(null)
+  })
+
+  it('closeMenus also dismisses the in-suggest dropdown', () => {
+    const ctx = makeCtx({ inSuggestFor: 'symbol' })
+    const m = createMenus(ctx)
+    m.closeMenus()
+    expect(ctx.inSuggestFor).toBe(null)
+  })
+
   it('updateFilterMenuValueTo sets the upper bound for between', () => {
     const ctx = makeCtx({ filterMenuValues: { age: { operator: 'between', value: '5' } } })
     const m = createMenus(ctx)

package/src/menus.ts

@@ -40,6 +40,7 @@ import {
   type TableFeatures,
 } from "./index";
 import "./sv-grid-scrollbar";
+import { untrack } from "svelte";
 import type { Snippet } from "svelte";
 import { getKeyboardIntent, getNextActiveCell } from "./keyboard";
 import {
@@ -115,6 +116,7 @@ import {
   buildBuckets,
   isInBucket,
 } from "./facet-buckets";
+import { splitInTokens, joinInTokens } from "./filtering/excel-filters";
 import {
   getColumnBaseValue,
   isGroupRow,
@@ -179,6 +181,34 @@ export function createMenus<
     };
   }
 
+  /** Current `in` / `notIn` token list for a column (from the filter-row value). */
+  function filterTokens(columnId: string): string[] {
+    return splitInTokens(ctx.filterRowValues[columnId] ?? "");
+  }
+
+  /** Add a value to a column's `in` / `notIn` list (no-op if already present). */
+  function addFilterToken(columnId: string, token: string) {
+    const t = token.trim();
+    if (!t) return;
+    const tokens = filterTokens(columnId);
+    if (!tokens.includes(t)) tokens.push(t);
+    updateFilterRow(columnId, joinInTokens(tokens));
+  }
+
+  /** Remove a value from a column's `in` / `notIn` list. */
+  function removeFilterToken(columnId: string, token: string) {
+    updateFilterRow(
+      columnId,
+      joinInTokens(filterTokens(columnId).filter((t) => t !== token)),
+    );
+  }
+
+  /** Toggle a value in a column's `in` / `notIn` list (checklist behaviour). */
+  function toggleFilterToken(columnId: string, token: string) {
+    if (filterTokens(columnId).includes(token)) removeFilterToken(columnId, token);
+    else addFilterToken(columnId, token);
+  }
+
   function toggleCheckboxWithKeyboard(
     event: KeyboardEvent,
     toggle: () => void,
@@ -193,7 +223,9 @@ export function createMenus<
     const menuFilter = ctx.filterMenuValues[columnId];
     return Boolean(
       menuFilter &&
-        (menuFilter.operator === "isBlank" || menuFilter.value.trim()),
+        (menuFilter.operator === "isBlank" ||
+          menuFilter.operator === "isNotBlank" ||
+          menuFilter.value.trim()),
     );
   }
 
@@ -201,9 +233,23 @@ export function createMenus<
     ctx.columnMenuFor = null;
     ctx.filterMenuFor = null;
     ctx.operatorMenuFor = null;
+    ctx.inSuggestFor = null;
     ctx.chooseColumnsPos = null;
   }
 
+  /** Open the `in` / `notIn` value-suggestions dropdown under a chip input. */
+  function openInSuggest(anchor: HTMLElement, columnId: string) {
+    const rect = anchor.getBoundingClientRect();
+    ctx.inSuggestPos = { x: clampMenuX(rect.left, 220), y: rect.bottom + 4 };
+    ctx.inSuggestQuery = "";
+    ctx.inSuggestFor = columnId;
+  }
+
+  function closeInSuggest() {
+    ctx.inSuggestFor = null;
+    ctx.inSuggestQuery = "";
+  }
+
   function openChooseColumns(event: MouseEvent) {
     event.stopPropagation();
     // Submenu behavior: keep the parent operations menu open and float the
@@ -351,21 +397,27 @@ export function createMenus<
   }
 
   function clearColumnFilter(columnId: string) {
-    if (ctx.valueFilters[columnId]) {
-      const next = { ...ctx.valueFilters };
-      delete next[columnId];
-      ctx.valueFilters = next;
-    }
-    if (ctx.filterMenuValues[columnId]) {
-      const next = { ...ctx.filterMenuValues };
-      delete next[columnId];
-      ctx.filterMenuValues = next;
-    }
-    if (ctx.filterRowValues[columnId]) {
-      const next = { ...ctx.filterRowValues };
-      delete next[columnId];
-      ctx.filterRowValues = next;
-    }
+    // `untrack`: read-modify-write on the filter maps. Keeps the method safe to
+    // call from a consumer's reactive `$effect` (e.g. via `api.clearFilter`)
+    // without capturing these reads as a dependency and looping. See
+    // `build-api`'s `setFilter` for the full rationale.
+    untrack(() => {
+      if (ctx.valueFilters[columnId]) {
+        const next = { ...ctx.valueFilters };
+        delete next[columnId];
+        ctx.valueFilters = next;
+      }
+      if (ctx.filterMenuValues[columnId]) {
+        const next = { ...ctx.filterMenuValues };
+        delete next[columnId];
+        ctx.filterMenuValues = next;
+      }
+      if (ctx.filterRowValues[columnId]) {
+        const next = { ...ctx.filterRowValues };
+        delete next[columnId];
+        ctx.filterRowValues = next;
+      }
+    });
   }
 
   // External pagination is controlled: emit the requested page/size and let
@@ -553,9 +605,14 @@ export function createMenus<
     updateFilterOperator,
     updateFilterMenuValue,
     updateFilterMenuValueTo,
+    addFilterToken,
+    removeFilterToken,
+    toggleFilterToken,
     toggleCheckboxWithKeyboard,
     isColumnFiltered,
     closeMenus,
+    openInSuggest,
+    closeInSuggest,
     openChooseColumns,
     openColumnMenu,
     openFilterMenu,

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')
+  })
 })