fix(lookup): skip empty cells in approximate MATCH/lookup search (HF-223)

Excel and Google Sheets ignore genuinely empty cells (but not empty
strings) when computing the lower/upper bound for an approximate match.
HyperFormula instead landed on an empty cell during binary search and
returned #N/A (its EmptyValue Symbol never matched the key), or, in
descending mode, reported the wrong position.

findLastOccurrenceInOrderedRange now runs the ordered search over a
compacted list of non-empty cell indices and maps the result back to the
original index space, so empty cells keep their slots and the matched
non-empty cell's original 1-based position is reported unchanged. When
the range has no non-empty cells the function returns NOT_FOUND, so an
all-empty range yields #N/A for every direction/bound instead of falling
through to the offset-0 branches. The in-memory ordered path in
AdvancedFind.findNormalizedValue skips EmptyValue for the same reason.
Empty strings are unaffected (text is ranked above numbers, so they
still terminate a numeric run). Exact match (matchType 0) is untouched.

Shared by approximate MATCH(+/-1), sorted VLOOKUP/HLOOKUP, and
XLOOKUP(searchMode +/-2). Tests for the public test suite are tracked
separately in handsontable/hyperformula-tests.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: marcin-kordas-hoc

CHANGELOG.md

@@ -11,6 +11,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 - Added an Indonesian (Bahasa Indonesia) language pack. [#1674](https://github.com/handsontable/hyperformula/pull/1674)
 
+### Fixed
+
+- Fixed approximate `MATCH`, `VLOOKUP`, `HLOOKUP`, and `XLOOKUP` incorrectly returning `#N/A` (or a wrong position) when the search range contained empty cells; empty cells are now skipped during approximate matching, consistent with Excel and Google Sheets. [HF-223]
+
 ## [3.3.0] - 2026-05-20
 
 ### Added

src/Lookup/AdvancedFind.ts

@@ -5,6 +5,7 @@
 
 import {DependencyGraph} from '../DependencyGraph'
 import {
+  EmptyValue,
   getRawValue,
   InternalScalarValue,
   RawInterpreterValue,
@@ -88,6 +89,13 @@ export abstract class AdvancedFind {
         return i
       }
 
+      // Skip empty cells in the approximate search, consistent with findLastOccurrenceInOrderedRange:
+      // Excel/Google Sheets ignore genuinely empty cells (but not empty strings) when looking for the
+      // lower/upper bound. EmptyValue would otherwise be ranked below every value by compare().
+      if (value === EmptyValue) {
+        continue
+      }
+
       if (compareFn(value, searchKey) > 0) {
         continue
       }

src/interpreter/binarySearch.ts

@@ -20,6 +20,12 @@ const NOT_FOUND = -1
  *
  * If the search range contains duplicates, returns the last matching value. If no value found in the range satisfies the above, returns -1.
  *
+ * Empty cells (EmptyValue) are skipped: they are not treated as ordered values during the
+ * approximate search. This mirrors Excel/Google Sheets, where MATCH/VLOOKUP/HLOOKUP/XLOOKUP
+ * ignore genuinely empty cells (but not empty strings) when looking for the lower/upper bound.
+ * The returned offset is always relative to the original range, so empty cells keep their slots
+ * and the position of the matched non-empty cell is reported unchanged.
+ *
  * Note: this function does not normalize input strings.
  */
 export function findLastOccurrenceInOrderedRange(
@@ -35,12 +41,31 @@ export function findLastOccurrenceInOrderedRange(
     ? (index: number) => getRawValue(dependencyGraph.getCellValue(simpleCellAddress(range.sheet, index, range.start.row)))
     : (index: number) => getRawValue(dependencyGraph.getCellValue(simpleCellAddress(range.sheet, range.start.col, index)))
 
+  // Collect the original indices of the non-empty cells, preserving their order. Empty cells break
+  // the sort invariant binary search relies on (compare() ranks EmptyValue below every other value),
+  // so the search runs over the compacted, empty-free index list and the result is mapped back to the
+  // original index space afterwards.
+  const nonEmptyIndices: number[] = []
+  for (let index = start; index <= end; index++) {
+    if (getValueFromIndexFn(index) !== EmptyValue) {
+      nonEmptyIndices.push(index)
+    }
+  }
+
+  // With no non-empty cells there is nothing to match against. Return early so the
+  // ifNoMatch branches below (which treat NOT_FOUND as "key past the edge of a non-empty
+  // list" and may return offset 0) are not reached for an all-empty range.
+  if (nonEmptyIndices.length === 0) {
+    return NOT_FOUND
+  }
+
   const compareFn = orderingDirection === 'asc'
     ? (left: RawNoErrorScalarValue, right: RawInterpreterValue) => compare(left, right)
     : (left: RawNoErrorScalarValue, right: RawInterpreterValue) => -compare(left, right)
 
-  const foundIndex = findLastMatchingIndex(index => compareFn(searchKey, getValueFromIndexFn(index)) >= 0, start, end)
-  const foundValue = getValueFromIndexFn(foundIndex)
+  const foundCompactedIndex = findLastMatchingIndex(compactedIndex => compareFn(searchKey, getValueFromIndexFn(nonEmptyIndices[compactedIndex])) >= 0, 0, nonEmptyIndices.length - 1)
+  const foundIndex = foundCompactedIndex === NOT_FOUND ? NOT_FOUND : nonEmptyIndices[foundCompactedIndex]
+  const foundValue = foundIndex === NOT_FOUND ? EmptyValue : getValueFromIndexFn(foundIndex)
 
   if (foundValue === searchKey) {
     return foundIndex - start
@@ -61,8 +86,8 @@ export function findLastOccurrenceInOrderedRange(
     }
 
     // orderingDirection === 'desc'
-    const nextIndex = foundIndex+1
-    return nextIndex <= end ? nextIndex - start : NOT_FOUND
+    const nextIndex = nonEmptyIndices[foundCompactedIndex + 1]
+    return nextIndex !== undefined ? nextIndex - start : NOT_FOUND
   }
 
   if (ifNoMatch === 'returnUpperBound') {
@@ -80,8 +105,8 @@ export function findLastOccurrenceInOrderedRange(
     }
 
     // orderingDirection === 'asc'
-    const nextIndex = foundIndex+1
-    return nextIndex <= end ? nextIndex - start : NOT_FOUND
+    const nextIndex = nonEmptyIndices[foundCompactedIndex + 1]
+    return nextIndex !== undefined ? nextIndex - start : NOT_FOUND
   }
 
   // ifNoMatch === 'returnNotFound'