docs(guide): document named ranges in formulas + fix limitations pointer (HF-222)

Adds a 'Using named ranges in formulas' section to named-expressions.md (behavior as function arg / operator operand / bare ref, incl. array mode) and replaces the inaccurate top-level named-ranges bullet in known-limitations.md with a neutral pointer. Docs-only.

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

Author: marcin-kordas-hoc

docs/guide/known-limitations.md

@@ -14,9 +14,7 @@ the full evaluation of expressions and condition statements. The
 most prominent example of this behavior is the "IF" function which
 returns a cycle error regardless of whether TRUE or FALSE causes
 a circular reference.
-* There is no data validation against named ranges. For example,
-you can't compare the arguments in a formula like this:
-=IF(firstRange>secondRange, TRUE, FALSE).
+* Named ranges behave differently depending on where they are used in a formula. For details, see [Using named ranges in formulas](named-expressions.md#using-named-ranges-in-formulas).
 * [Custom functions](custom-functions.md) don't automatically recalculate the size of their [result arrays](custom-functions.md#return-an-array-of-data) when the formula dependencies change.
 * There is no relative referencing in named ranges.
 * The library doesn't offer (at least not yet) the following features:
@@ -38,37 +36,3 @@ you can't compare the arguments in a formula like this:
 * The INDEX function doesn't support returning whole rows or columns of the source range – it always returns the contents of a single cell.
 * The FILTER function accepts either single rows of equal width or single columns of equal height. In other words, all arrays passed to the FILTER function must have equal dimensions, and at least one of those dimensions must be 1.
 * Array-producing functions (e.g., SEQUENCE, FILTER) require their output dimensions to be determinable at parse time. Passing cell references or formulas as dimension arguments (e.g., `=SEQUENCE(A1)`) results in a `#VALUE!` error, because the output size cannot be resolved before evaluation.
-
-### OFFSET function
-
-HyperFormula resolves the OFFSET function at parse time rather than during evaluation. The parser inspects the arguments and rewrites the expression into a plain cell reference or range. This keeps the dependency graph accurate but imposes several restrictions.
-
-* The first argument must be a reference to a single cell. Passing a range causes the cell to store a parser error (the API call itself does not throw — read the error via `getCellValue`).
-
-  ```js
-  // Cell A1 stores a parser error — the first argument must be a single cell, not a range
-  hf.setCellContents({ sheet: 0, row: 0, col: 0 }, '=OFFSET(A1:B1, 0, 0)');
-  ```
-
-* The row-shift, column-shift, height, and width arguments must be static integer literals known at parse time. Cell references and formulas passed as shift or size arguments cause the cell to store a parser error.
-
-  ```js
-  // Cell A1 stores a parser error — the row-shift argument must be a static integer literal
-  hf.setCellContents({ sheet: 0, row: 0, col: 0 }, '=OFFSET(A1, C3, 0)');
-  ```
-
-* The height and width arguments must be bare positive integer literals (the parser accepts only `NUMBER` AST nodes). Unary `+` prefixes, parenthesised expressions, values less than 1, and non-integer values are rejected at parse time.
-
-* When the computed target falls outside the sheet, the parser stores a `#REF!` error in the cell at parse time (rather than during evaluation) with the message *Resulting reference is out of the sheet*.
-
-  ```js
-  // Cell A1 stores #REF!
-  hf.setCellContents({ sheet: 0, row: 0, col: 0 }, '=OFFSET(A1, -1, 0)');
-  ```
-
-* OFFSET is resolved at parse time, so `getCellFormula` returns the computed reference, not the original `OFFSET` call.
-
-  ```js
-  const hf = HyperFormula.buildFromArray([[1, 45, '=OFFSET(A1, 0, 1)']]);
-  hf.getCellFormula({ sheet: 0, row: 0, col: 2 }); // '=B1'
-  ```

docs/guide/named-expressions.md

@@ -87,6 +87,18 @@ hfInstance.setCellContents({sheet: 0, col: 2, row: 0}, [['=SUM(SalesData)']]);
 hfInstance.setCellContents({sheet: 0, col: 2, row: 1}, [['=SUM(SalesData) * TaxRate']]);
 ```
 
+## Using named ranges in formulas
+
+A named expression that resolves to a range of cells behaves differently depending on where it is used:
+
+- **As a function argument** — it works as expected. `=SUM(myRange)`, `=COUNT(myRange)`, and `=INDEX(myRange, 1, 1)` all operate on the full range.
+- **As an operand of an operator** — the range is reduced to a single cell before the operation. In `=myRange + 1`, only the cell of the range that shares the formula's row (for a vertical range) or column (for a horizontal range) is used. If the formula's row or column falls outside the range, or the range is two-dimensional, the result is a `#VALUE!` error.
+- **As a bare reference** — `=myRange` on its own returns a `#VALUE!` error; a range cannot be placed directly into a single cell.
+
+The range is reduced before the operator runs, so `=SUM(myRange + 1)` receives a single value rather than adding 1 to every element.
+
+When array arithmetic is enabled (`useArrayArithmetic: true`), named ranges still work as function arguments and aggregate correctly, but they do not spill: `=myRange + 1` returns a `#VALUE!` error rather than producing one result per element.
+
 ## Available methods
 
 These are the basic methods that can be used to add and manipulate named